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Preface 


The object of the book is, hopefully, to steer interest in computing 
away from mundane games and towards more ‘serious’ areas. 
Although aimed slightly above the beginner stage, persons new to 
computing should not be deterred from getting to grips with the 
contents. The earlier chapters in particular may help to nip bad 
programming habits in the bud. Experienced users, wanting to gain 
complete control over their machines, may find solace in later 
chapters where more complex subject areas are substantially 
covered. 

In contrast with the ‘Fifty zapping games for the — insert name 
here’ type of book, a number of the included subjects may, on the 
surface, appear a little dry in content. This may be rather unsettling 
for some, but the rewards for perseverance are high. Even an 
elementary background knowledge of computing techniques and 
algorithms can save many unfruitful hours at the keyboard. The 
book is also intended to be used as a reference source containing 
many ‘off the shelf’ subroutines for inclusion into readers’ own 
programs. 

This book, as expected from the title, contains numerous listings 
of subroutines. The first few are simple. In fact simple ones were 
deliberately chosen in order to reduce hair loss when confronted 
with the nastier species which inhabit the later chapters. They have 
all been tested and are, we hope, free from serious bugs. However, 
because many of them are supported by detailed explanations, it is 
hoped that you will consider them more as guidelines for creating 
your own, perhaps better, versions. Most of them are written in 
BASIC but some ultra-fast machine code routines for sorting string 
array data have been included. These can be entered by means of 
the Amsoft Assembler or by means of a hex loading program which 
we have supplied. Those who have never seen a machine code 
version of the Quicksort algorithm in action should be agreeably 
surprised. 

A collection of isolated subroutines can be useful but they are 
unlikely to inspire confidence unless they are seen nestling inside 
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some practical programs. Each subroutine listing includes a short 
calling program for testing with different parameters but in addi- 
tion, several complete practical program listings are supplied 
providing final consolidation material. The programs include a 
sophisticated general purpose filing system, an index processor, a 
complete music sequencer, a general solution of polynomial 
equations, a function plotter that can display up to three graphs on 
the same axis with automatic scaling and a histogram generator. 
The early chapters give a brief overview of the Amstrad machines 
but we have avoided trying to ‘rewrite’ the User Instruction manual 
because, in the main, it is an excellent example of unequivocal 
descriptive writing. However, we felt that some of the commands, 
particularly those which could be described as innovative, deserved 
an alternative treatment so we have concentrated on these, to the 
exclusion of the standard command set found in traditional BASIC. 


AP Stephenson and DJ Stephenson 


Important notes 


Exponential sign 

The “*” character, used in some of the subroutines and programs 
listed in this book, is the exponential operator, CHR$(94). On 
Amstrad machines, the key has the legend “ { ”. 


Integer division sign 

Many of the subroutines and programs make use of the integer 
division operator CHR$(92) or “\”. Please note that programs in- 
tended to use this may not work correctly if the normal division 
operator, CHR$(47) or “/”, is entered by mistake. 


Tape machines 

Readers using casette tape data storage are directed to read pages 6 
and 7 concerning the permanent allocation of cassette buffers prior 
to using any prgrams in Chapters 7 and 8. 
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Amstrad BASIC and 
structured programming 


This introductory chapter briefly covers the main hardware features 
of the Amstrad machines and goes on to discuss BASIC and salient 
issues involved in structured programming. 


Special features of the machine 


The growing popularity of the Amstrad CPC464/664 machines could 
be due to one or more of the following features: 


1 The custom-built video monitor. 

2 The self-contained tape unit in the CPC464. 

3 The quality of the BASIC interpreter. 

4 The provision of a proper keyboard with an additional numeric 
key pad. (A ‘proper’ keyboard is one which does not employ one of 
those rubbery membrane contraptions.) 


Although none of these features is unique in itself, it is unusual to 
find all of them together in such moderately priced machines. It is 
also blessed with a rather attractive appearance which manages to 
convey the impression of ruggedness without sacrificing the 
mandatory ‘high-tech’ look. There are, of course, other features 
such as programmable sound chips, high resolution graphics, 
facilities for connecting the ubiquitous joystick but, because they are 
now almost commonplace, we have not mentioned them. 

Programs, and of course subroutines within programs, should 
always be designed to fully utilise any specific advantages a 
machine may offer. In view of this, it is worth examining the 
features in detail, starting with the importance of a resident video 
monitor. 


Why a video monitor? 

A microcomputer, however powerful and sophisticated, will fail to 
impress a user for long if the quality of the display is poor. The 
majority of moderately priced computers on the market are in- 
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tended to be operated with a normal domestic television acting as 
the video display. Buried in one corner of the circuit board will be a 
small gadget known as the UHF Modulator which is responsible for 
producing some rather awe-inspiring changes to the computer 
output in order to trick the aerial socket of the TV set into thinking it 
is dealing with a normal broadcast picture. The thing does its best 
but it is not surprising that a good deal of unwanted video slush 
accumulates on the way. On top of all this, we should remember 
that a broadcast picture is analogue in nature. That is to say, it is a 
composite waveform of smoothly varying energy. There is nothing 
wrong with a TV set when used for viewing broadcast pictures. The 
resolution of 625 lines combined with a video bandwidth in the 
order of 5.5 MHz is quite adequate for looking at American soap 
operas, but it is quite unable to respond quickly enough to the flow 
of on/off signals spewed out from a digital computer. Because of 
these inherent defects, a TV set acting as a video monitor is an 
unsatisfactory compromise. The fact that it has hitherto been widely 
accepted is mainly because an old second-hand TV set can usually 
be bought cheaply, or the family set can be periodically released for 
computer use. There is also truth in the old adage — what you never 
have you never miss. However, if you see the computer output on a 
decent monitor instead of a TV, contentment rapidly changes to 
envy. A custom-built video monitor is an enormous improvement. 
In the first place, there is no need for that dreadful UHF modulator 
because the output of the computer is fed directly to the RGB 
circuitry of the monitor. Unlike the TV, it understands the computer 
signal without relying on extra trickery. The computer output text is 
rock steady and substantially free of annoying smudges and 
kaleidoscopic colour fringeing. The most dramatic improvement, 
apart from the extra cleanliness of the display, is the ability to 
resolve 80 characters-per-line text. Many home computers have a 
facility for outputting text at 80 characters per line but, unless a 
proper video monitor is used, the characters are smudgy, difficult to 
read and could easily lead to serious eye strain if viewed for long 
periods. On the other hand, the Amstrad monitors, both the 
monochrome and the colour version, produce an easily readable 80 
character per line display. The colour version is slightly inferior to 
the monochrome model but is quite acceptable. The main reason for 
the degraded performance is that a colour CRT is itself composed of 
small phosphor dots or stripes, whereas a monochrome tube has an 
even coating of phosphor. In all programs and subroutines which 
are heavily text bound, such as filing and business oriented 
systems, the popular 40 character line is far too restrictive so it is 
sensible to take full advantage of the 80 character/25 line display 
offered by Mode 2. 

Before leaving the subject, it is worth mentioning one unusual 
feature of the Amstrad video monitor. It houses the computer power 
supply circuitry. A considerable proportion of the heat generated by 
a computer comes as a by-product from its own power supply. Since 
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the biggest enemy of the modern silicon microchip is heat, the 
reliability is much improved by keeping the power supply well 
away from the computer circuit boards. Some popular computers 
solve this problem by having the power supply as an external plug- 
in black box. This is all very well from the technical point of view but 
this means yet another lead which, together with the cassette lead, 
the TV lead and mains cable, helps towards an impression of 
organised chaos. Besides, every extra external plug and socket 
detracts from the reliability of an overall system. 


The tape unit 

The cassette tape unit on the majority of home computers is a device 
which must be purchased separately and plugged into one of the 
output sockets at the back. The self-contained unit in the Amstrad 
CPC464 has the following advantages, over and above the obvious 
saving in additional cost: 


1 There are no untidy connecting cables and consequently, no 
trouble with faulty plug connections. 


2 The integrated design allows the signal levels between computer 
and tape unit to be optimised during the manufacturing stage. Thus 
there is no need for fiddling around with volume and tone controls 
to get a program to load. 


3 Asadirect result of the optimised signal levels, the speed of data 
transfer can be increased without seriously jeopardising data. 


There is a choice of two tape speeds, the normal (default) speed of 
1,000 baud or a software selectable higher speed of 2,000 baud. For 
the record, one baud is a unit representing one information bit per 
second. Because it is already a rate, in the same sense as the nautical 
knot, it is not strictly correct to speak of a baud ‘rate’. The selection 
procedure, carried out by the keyword SPEED WRITE, is as follows: 


To establish 1,000 baud conditions, enter SPEED WRITE 0 
To establish 2,000 baud conditions, enter SPEED WRITE 1 


These are nominal figures, as indeed are all quotations in baud, 
because they are based on the assumption that the data consists of 
regular alternations of binary bits. That is to say, the signals are 
assumed to be of the form 1,0,1,0,1,0,1,0 etc. Thus, the baud quoted 
is based on statistical averages. Another often neglected factor is the 
presence of formatting data such as end of block characters and inter 
block pauses in the data transfer. 

When reading a file back from tape, the Amstrad senses the baud 
rate which was used when the file was recorded so there is no need 
to worry about adjustments for baud rate. LOAD ‘filename’ or 
INPUT#9, <parameter list> will handle the read process, irrespec- 
tive of the baud rate used at the time when the file was saved. 
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Speed of information storage 

It is all very well quoting speed in baud but, if you are a newcomer 
to computing and the Amstrad CPC464 is your first machine, you 
will appreciate a more down to earth measurement of tape speed. 
For example, we may be more interested in knowing how long it 
takes to store a typical page of A4 text? To answer this, we must 
start with the time it takes to store a single keyboard character. 
Information characters are passed to tape in serial form. That is to 
say, the information stream is only one bit ‘wide’. One character in 
the ASCII code requires 8 bits but, as previously stated, at least 
another couple of bits are required to signal the beginning and end 
of each character so we end up with a provisional figure of 10 bits per 
character. A tape speed of 2,000 baud (2,000 bits per second) means 
that the character speed is 2,000/10=200 characters per second or 
12,000 characters per minute. If we assume the average word in the 
English language contains five letters, this is equivalent to 12,000/5= 
2,400 words per minute. A typical page of typed text, using double 
spacing between lines, contains about 28 lines of 13 words per line — 
364 words per page. At 2,400 words per minute, the speed of data 
transfer via cassette tape works out to about six and a half pages of 
typed text per minute. 


Choice of baud rate 

In general, the higher the baud, the greater the chance of a read 
error so if the data you wish to store on tape is particularly precious 
it is probably advisable to use 1,000 baud. However, we should 
mention that we use the higher rate consistently and have never yet 
encountered a read error. Perhaps we are lucky but it appears to be 
an extremely dependable system. The reliability of 2,000 baud may 
not be quite as good if a program is recorded on one machine and 
played back on another. This is because there may be slight 
differences in the alignment of properties of the record/playback 
head. For economy, the head gap is set to a compromise for record 
and playback. Strictly, separate record and playback heads should 
be fitted and aligned for maximum performance. So, if you intend 
your program to be read on other people’s machines, it might be 
safer to record at 1,000 baud. 


The leader tape 

The majority of cassettes available in the High Street shops have 
several inches of blank leader tape before the normal oxide coated 
region. The leader makes a strong mechanical joint with the 
winding spool besides having a cleaning action on the record/ 
playback head but, naturally, it cannot store information. If you 
start the recording process too early, that is to say, before the leader 
has passed the recording head, the first part of your data may be lost 
and will be impossible to recover when you later try to load it back. 
To prevent such a catastrophe it is worth pressing the FF button for 
a couple of seconds after a full rewind in order for the leader tape to 
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pass over the heads before you begin the recording procedure. A 
good plan is to advance the tape until the digital counter on the 
cassette unit reaches 5. You can buy special leaderless cassettes but 
they are not so readily available. Cassettes, even without leader 
tapes, can lead to a false sense of security so it is still advisable to 
allow the first few inches of tape to pass. These first few inches can 
be degraded by the tight coiling around the spool. So-called ‘digital 
quality’ tapes often have larger diameter spools so the coiling is less 
tight on the inner layers. You should think carefully before buying 
bargain-price cassettes. Saving a small amount on the price of a 
cassette can often be false economy. Good quality cassettes, par- 
ticularly those intended for digital data, are manufactured to closer 
tolerance limits so there is far less chance of blemishes over the 
oxide surface. Irregularities in the oxide coating, called drop-outs, 
are relatively unimportant when recording normal music but one bit 
reversed on a data tape could lead to chaos. 


Labelling cassettes 

The importance of labelling increases in direct proportion to the 
number of cassettes in use. If you have only two or three tapes, it is 
probably a waste of time writing labels because you will be 
constantly changing the contents. In fact it is probably better during 
development stages to forget labels altogether and use a felt pen 
directly on the cassette. However, as your collection of subroutines 
and programs grows, it is wise to adopt a methodical approach. 
Because the labels specially designed for cassettes tend to be a little 
overpriced you may just as well buy a roll of pre-gummed plain 
labels and cut them to size as you want them. Stick the labels on the 
cassette itself, not on the plastic container, because either the 
cassette could get into the wrong case, or once you stick a label on 
the case, it is very difficult to remove it without scraping and leaving 
a smudgy mess behind. On the other hand, labels seem to peel off 
cleanly from the body of the cassette. If cassette contents are to be 
changed, it is better to replace the entire label rather than make 
alterations. A label with multiple alterations looks scruffy and 
reduces confidence in the quality of the contents. Another method 
is simply to label the cassettes 1, 2, 3 etc and list the contents in a 
tape register book. The trouble with registers is that initial enthu- 
siasm for their upkeep often wanes. It doesn’t really matter what 
system you use providing you have one and that you stick to it. 


Disc storage 


The CPC664 uses a 3” compact floppy disc drive (optional on the 
CPC464). The discs are double sided with a storage capacity of 170K 
per side. However, apart from speed, a few extra processing 
facilities and the provision of a disc catalogue, all the material in this 
book except where specifically stated otherwise, will apply to both 
disc and cassette tape. 
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Cassette data blocks 

A cassette unit, because it is a mechanical system, operates thous- 
ands of times more slowly than the computer. To allow for the time 
difference, computers utilise a temporary buffer area in RAM. The 
Amstrad CPC464 employs a 2K area of memory, called a block, 
which is used as a buffer between the cassette and the computer. 
Data transfers between computer and cassette take place from 
within this buffer area. When a program is being loaded, the screen 
message displays each 2K block number. 


Allocation of cassette buffer area 

The Amstrad uses dynamic allocation for cassette files. This means 
that space for the cassette buffer is allocated only when needed. 
There are sound reasons why the designers decided on dynamic 
allocation rather than the conventional fixed buffer area. Many 
programs may not use cassette data files so why waste valuable 
RAM by reserving space that may not be used? For instance, a disc 
drive may be connected which may render the cassette unit re- 
dundant in the future. The Amstrad CPC464 can support two open 
cassette files. A 2K buffer area is needed for each of the input and 
output buffers thus making 4K in total. 

The highest memory location available for BASIC is stored in the 
variable HIMEM. Strings are stored from HIMEM downwards and 
are referred to, rather irreverently, as the ‘heap’. In order for the 
cassette buffers to be allocated, BASIC performs a housekeeping 
operation to ensure that the heap is as small as possible, and then 
physically moves it down in memory by 4K. HIMEM is subse- 
quently set to this lower value. When the cassette buffer has 
performed its task, BASIC tries to reclaim the memory taken by the 
buffer. It can only do this if the buffer area is immediately above 
HIMEM. Subject to this proviso, the heap is moved back to its 
original location and HIMEM reset to its default value. It is easy to 
see why, with all this movement going on, it is called ‘dynamic’ 
allocation. The general principle is fine in the majority of cases but is 
a bit of a nuisance with RAM based files. The time taken to 
housekeep and continually readjust the heap can take anything up 
to a couple of minutes to perform, depending on the number of 
strings in the heap. Such a delay can be annoying but, fortunately, 
there is a way of opting out of the system. The buffers can be 
permanently, instead of dynamically, allocated by the following few 
program lines: 


10 OPENOUT “buffer” 
20 MEMORY new 
30 CLOSEOUT 


where ‘new’ is the updated value of HIMEN given by the following 
relation: 
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new=(default value of HIMEM)-4K-1 


The —1 term is needed to ensure that the cassette buffer, opened in 
line 10, is not immediately above HIMEM when the file is closed 
(see above). BASIC is thus unable to reclaim the memory allocated 
to the buffers. However, if, at a later stage in the program, the 
cassette buffers are needed again, the previously allocated space 
will be reused. 


A practical example 

Assuming a perfectly standard CPC464 machine with no extras, the 
default HIMEM will be &AB7F. Reducing HIMEM by 4K gives 
&9B7F and a further reduction of 1, to comply with the above, 
makes &9B7E. Therefore, the cassette buffers can be statically 
allocated on a standard machine by the following: 


10 OPENOUT “buffer’’ 
20 MEMORY &9B7E 
30 CLOSEOUT 


An alternative version is: 


10 OPENOUT “buffer” 
20 MEMORY HIMEM-1 
30 CLOSEOUT 


Although the latter version is not marred by the presence of the hex 
constant and may appear preferable, it suffers a severe disad- 
vantage in that a further 4K will be confiscated each time a program 
containing the above lines is reRUN. Using the former method it is 
easy to reserve a chunk of memory for machine code routines at the 
same time. For instance if &200 (512 decimal) bytes are required for a 
machine code routine then line 20 could be changed to 


20 MEMORY &997F 


There is now room for some machine code to be assembled from 
&9980 onwards. 


Limiting the BASIC area 

The memory area above that used by BASIC is, in theory, available 
for other purposes — for example, machine code subroutines. The 
top address of the area, currently occupied by BASIC, is always 
available in the dynamic variable HIMEM. The programmer can 
restrict the BASIC space by assigning a fixed address to the pseudo- 
variable MEMORY. For example. MEMORY &2000 will set the 
upper address limit for BASIC. Memory above this, normally 
claimed by BASIC, is then released for machine code. 
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Amstrad BASIC 


The language, described under the generic title of BASIC is well 
known to all microcomputer users. It is less well known that some 
critics, within the higher echelon of the profession, adopt a some- 
what patronising attitude towards the poor language. They appear 
to have two major moans. The first is that BASIC is an interpretive, 
rather than a compiled, language. That is to say, each line in BASIC 
is translated into machine code and then separately executed before 
the next line is translated. Every time a program is RUN, the lines 
have to be re-translated. A compiled language, on the other hand, 
translates (it is called compiling) the entire program into machine 
code, where it thereafter becomes the ‘object’ program. The pro- 
gram can, from then on, be run in this form over and over again 
without the necessity to translate each time. Obviously, a compiler 
language will score in terms of execution speed at RUN time over an 
interpretive language. There is also a greater saving in memory 
because, once compiled, the original high-level program (the source 
code) can be discarded, therefore freeing valuable RAM space. 
However, an interpretive language is much easier to manipulate 
than the compiler language. Bugs can be cleared and modifications 
made to a program without the trouble of re-compiling. In fact, one 
of the reasons for the popularity and growth of home computing is 
directly due to the fact that BASIC is an interpretive language and, 
to use a hackneyed phrase, ‘friendly’ to the novice programmer. 

The second moan of the critics is directed against the structure of 
BASIC programming. They say that it is unsuitable for writing good 
‘structured’ programs. We shall be discussing the virtues and 
techniques of program structure later on but, for the moment, we 
shall assume you have at least a vague idea of its meaning. Now 
here, the critics do have a point. It is true that the original designers 
of BASIC failed to embody certain features which characterise a 
well-structured language. After all, the central design strategy of the 
language was ease of use by non-specialist personnel. In fact the 
very name BASIC is short for ‘Beginner’s All Purpose Symbolic 
Instruction Code’. The darling of the structuralist school is the 
language called PASCAL. Here is a language which was designed, 
almost with religious fervour, in accordance with the rules and 
principles of structure. It is said to be impossible for anyone to write 
a badly structured program in PASCAL. One cannot helpa feeling of 
unease at this claim. If we can’t write bad programs, how can we 
swagger or feel superior when we write good ones? 

The critics do not always take into account the fact that BASIC, 
like spoken languages, is changing. New commands have been 
introduced and the grammar (syntax) has undergone subtle 
changes. Some machines, including some which are extremely 
popular at this time, still employ rather old fashioned primitive 
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dialects of BASIC. It is, perhaps, out of place here to discuss the 
merits of rival machines but credit should be given to the BBC for 
the excellent BASIC version they specified for the Acorn-designed 
microcomputer. It was a pioneering, and successful, attempt to raise 
the status of BASIC and to make it easier to write reasonably well- 
structured programs. BBC BASIC, as it has come to be called, is 
practically a benchmark upon which to judge other versions. The 
Amstrad CPC464/664 version of BASIC appears, in many ways, to 
be modelled on the BBC. It is sad that procedures, which are a 
superior kind of subroutine and play such an important part in 
structured programming, are not supported. If they had been, this 
book would most certainly have been entitled ‘Procedures and 
Functions for the Amstrad CPC464/664’. However, as we shall see 
later, there are compensations in the form of extra commands which 
encourage structure and at the same time ease the task of pro- 
gramming — the WHILE/WEND, ROUND and PRINT USING, to 
name but a few. 

Although structure is important, there are other features of a high 
level language which ease the life of a programmer. Interrupts for 
example. Amstrad appear to have gone out of their way to make it 
easy for a BASIC programmer to use interrupts. It has always been 
considered a trifle adventurous to tamper with the interrupt system 
of a microcomputer. Anyone who has tried this, usually by resort- 
ing to machine code, will no doubt have encountered the micro- 
processor’s anger when frontal assaults are made on its interrupt 
lines. One false move and the silicon wretch withdraws all co- 
operation and crashes the operating system. These unpleasant 
consequences can be avoided on the Amstrad because the BASIC 
provides three commands, EVERY, AFTER and REMAIN, which 
allow us safe access to the interrupt system plus a choice of four 
independently controlled timers. 


Structured programming 


We have mentioned structure several times without attempting a 
formal definition. As a matter of fact, it is doubtful if a formal 
definition has any value nowadays. The set of disciplines forming 
the core of structure arose out of necessity many years ago. In the 
beginning, programmers of digital computers were primarily indi- 
vidualists and the media’s view of one was a shabbily dressed 
intellectual with a domed forehead, staring eyes and prone to the 
wearing of brown corduroy trousers. He was also supposed to be 
arrogant, undisciplined and conscious of his position in the socio- 
economic scale. Like most other attempts by the media to glamorise 
the unglamorous, such a view was a caricature. However, as far as 
being intellectual and undisciplined, the media got it right. In those 
days, the computer was a shocker to program and memory was 
costly — several thousand times more costly than today. And yet, 


10 


Amstrad BASIC and structured programming 


those pioneers worked miracles. They tortured their brains trying to 
evolve cunning tricks to save memory and to squeeze the last ounce 
of power from their contraptions. The primary consideration was to 
make the program work as fast as possible using the absolute 
minimum amount of RAM. (It was called ‘core memory’ in those 
days.) Unfortunately, excessive preoccupation with memory 
economy at the expense of all else led to some appalling disasters. 
Ambitious programs, full of clever but obscure tricks, were often 
understood only by a particular programmer. Because of the un- 
disciplined design, programs which took only weeks to write often 
took months to debug. It was not unusual for a lengthy and expen- 
sive programming project to be scrapped and redesigned afresh 
because the bugs in the original could not be traced, particularly if 
the original programmer had passed on. To make matters worse 
they were difficult and sometimes impossible to modify when the 
need arose. Eventually, it was realised that memory efficiency can 
be a false idol when considering overall cost-effectiveness. The cost 
of programming could be greater than the cost of extra memory. 
Gradually, a program became to be judged more on: 


1 the ability to be understood by those of moderate programming 
ability. This means that, as far as possible, programmers would 
avoid using clever tricks and concentrate on a few recognised and, 
preferably, standardised procedures, 


2 the ease with which bugs could be traced and cured, 


3 the ease with which modifications could be made to one part of a 
program without introducing chaos in another. 


Thus, memory was to be sacrificed in return for simplicity and 
uniformity of design. There was still room for the work of genius 
providing it was tempered with discipline and compassion for the 
limited intellect of normal humans. Programming was trying to 
become more of a science than an art. 


The three structures 


It was proved by an eminent mathematician that all tasks amenable 
to programming by a digital computer could be achieved with a 
combination of only three basic forms — he called them ‘structures’. 


1 The sequence structure 
This was a series of commands to be executed sequentially. As a 
simple example, using BASIC: 


100 INPUT “Enter velocity”;V 
110 E=(Mass* V“2)/2 

120 Power=E/2 

130 PRINT Power 


The three structures 
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SEQUENCE STRUCTURE 
CONDITIONAL STRUCTURE 


(c) 





Fig 1.1 LOOP STRUCTURE 


Don’t worry about the sense of these lines. The essential point to 
grasp is that there are no branches anywhere. The statements are 
executed one after the other. It can be represented in flow chart 
form as a simple rectangle as shown in Figure 1.1 (a) or, if more 
complex, split into a series of rectangles. 


2 The conditional structure 

In BASIC, this is equivalent to the IF/THEN/ELSE command. It 
enables either of two possible actions to be performed, depending 
on whether the condition is true or false. The flow chart form is 
shown in Figure 1.1 (b). A simple BASIC example would be: 


100 IF A<B THEN PRINT A ELSE PRINT B 
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3 The loop structure 

The common loop structure is the WHILE/WEND command. It 
generates a repetitive loop performing some action WHILE a con- 
dition remains true. The loop exits immediately the condition is 
found to be false. Note carefully that if the condition is false on 
initial entry to the loop, the action is not performed at all. The flow 
chart form is shown in Figure 1.1 (c). An example in BASIC is: 


100 WHILE A <> B 
110 PRINT A 

120 A=A+1 

130 WEND 


These are the three structures which formed the core of the 
discipline which became to be known as structured programming. 
Each of these structures can, of course, be nested. Thus we could 
have a WHILE/WEND loop inside another or in one arm of an IF/ 
THEN/ELSE structure. Obviously, many other structures exist but 
we should remember that the fundamental idea behind the original 
aim was to restrict the choice, as far as practical, to these three and, 
more importantly, that all structures only have one input point and 
one output point. Examine the flow charts again in Figure 1.1. to 
confirm this. It is considered heresy to use a structure which has 
more than one input or one output point. 


The downfall of the GOTO 


If the restriction on input and output points is observed to the letter, 
we are forced to the conclusion that the beloved GOTO in BASIC is 
an enemy of structure. We say ‘beloved’ because it is a popular 
device with so many of us. The trouble is that the GOTO has been a 
valuable, indeed almost necessary, old friend and suddenly to learn 
that it must be avoided like the plague can be quite distrubing. It is 
so easy to slip in GOTOs at various points in a program. So easy in 
fact that it grew into a habit with many of us. BASIC came to be 
known as the spaghetti language because of the tangled flowpaths 
which kept wobbling up and down between line numbers. Trying to 
trace bugs from within a maze of GOTOs can and has led to 
nervous exhaustion. Some popular machines still hang on to old- 
fashioned versions of BASIC which do not support the IF/THEN/ 
ELSE structure. All they have is the primitive IF/THEN which, more 
than any other command, encourages dependence on the GOTO. 
To see why this is so, assume that at some stage in a program we 
want to: 

Print ‘YES’ if A=1 but ‘NO’ if A is not equal to 1. Using IF/THEN, 


100 IF A=1 THEN PRINT ‘YES’: GOTO 120 


The downfall of the GOTO 


110 PRINT ‘NO’ 
D208 2 ois. areas Oe tae 


Using IF/THEN/ELSE 


100 IF A=1 THEN PRINT ‘YES’ ELSE PRINT ‘NO’ 
DLO erie: tas cee, rete 


Figure 1.2 shows flow charts of both methods. You will agree that 
the IF/THEN/ELSE method is tidier and easier to follow than the 
first version. There are times when the ELSE part is not required, in 
which case it is legal to miss it out. 












Print "YES" Print "YES" 


IF / THEN STRUCTURE IF / THEN / ELSE STRUCTURE 
OLD FORM NEW FORM 


Fig. 1.2 


Structure and efficiency 


It must be emphasised that structured programming as defined 
above is not necessarily efficient programming. For example, it is 
often more efficient to use GOTOs instead of a WHILE/WEND. 
However, avoid GOTOs as far as possible but not religiously. It is 
absurd to avoid the odd GOTO in situations where it would save 
yards of programming lines. Although the ideas behind structure 
are sound, it is unlikely that you will, neither should you, obey 
them as if they were commandments from above. We should 
understand that traditional BASIC was not intended, and certainly 
not designed, for structured programming. The extra commands 
available in the Amstrad CPC464/664 and certain other machines 
have allowed programmers to take structure more seriously but the 
language has still a long way to go before it can be classed alongside 
ALGOL (the original structured high-level language) and PASCAL 
(the modern variant). 
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The modern interpretation of structure 


We have discussed structure from the historical angle. The original 
concepts have been expanded and the term is now used in a much 
looser sense. In fact many writers, rightly or wrongly, use the term 
to describe any programming methods which are ‘modular’ in form, 
well constructed, easy to amend. Thus, when we now speak of a 
program as being ‘well structured’, all we might mean is that it is 
‘nicely laid out’. In this book, it would be neither profitable or 
interesting to enter into arguments as to whether such a view 
degrades the concepts of structure. Even if it does degrade the 
word, we shall, from now on, tend to use the word structure in this 
loose sense. 


Modular programming 


Strictly, modular programming is nothing more than a program 
design method. It refers to the technique of dividing a large 
programming task into separately testable modules. Here are three 
well established guidelines (not rules) which it pays to follow: 


1 Each module should, preferable, have only one identifiable 
function. 

2 Each module should have only one input and one output point. 
3 Each module should be capable of independent testing outside 
the program in which it is to be used. 


With regard to (3) above, a complete test often requires a short 
dummy program to supply the module with some data. 


The advantages of modular programming 

1 Constructing one module at a time is a simpler task than writing 
an entire program from scratch. 

2 Once a module has been tested, it could be of use in other 
programs. 

3 A library of general purpose modules can be built up for future 
use. 

4 Because modules are virtually separate entities, they can be 
improved in the light of experience. 

5 Large programs can be constructed by teamwork. Each member 
of the team can be made responsible for one set of modules. 


We should point out that modular programming is not to be 
treated as an alternative to structured programming. In fact, each 
module should still be designed in accordance with the guidelines of 
structure we have treated above. 

Modular programming has some disadvantages. For example, 
trouble may arise when the time comes to fit a set of modules 
together to form a complete program. The fault may, but shouldn't 
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be due to a faulty module. On the other hand, the program skeleton 
which integrates the modules may not be calling on the modules in 
the right order or may not be supplying the modules with the correct 
parameter. There are two ways to organise modular program de- 
velopment. They have attracted rather undignified names. One is 
called the top-down method and the other the bottom-up. 


Top-down design 


To adopt the top-down method, you first design the supporting 
framework of the program. We shall call this the control section. The 
design of the individual modules then begins. As each module is 
completed, it is thoroughly tested before insertion at the correct 
position in the control section. The places in the control program 
which are not yet occupied by modules are filled by short program 
‘stubs’. These stubs can be quite functionless. Indeed, they could 
take the form of a short screen message such as, ‘OK UP TO 
POINT 1’, followed by END. The program is re-tested as each 
stub is replaced by a proper module and, eventually, all stubs are 
replaced by modules. The program should then work first time — we 
hope! Bearing in mind that some modules rely on other modules, 
we must make due allowance for some temporary ‘faults’ until the 
missing module is supplied. If one module, say Module 3, requires 
Module 4 to be present, then it is prudent to fit Module 4 first. 


Bottom-up design 


This method employs a completely opposite procedure. The 
modules are designed first and tested or some may be selected 
ready-made from a library. Last of all, the control section to suit the 
current task is designed and the modules fitted. 


It is difficult to lay down any hard and fast rules as to which of the 
two methods should be used. As far as this book is concerned, the 
tendency will be towards bottom-up. That is to say, we shall be 
constructing general purpose modules to form a library. Providing 
the library is well stocked, the task of programming is reduced to 
designing the control framework and selecting a suitable set of 
modules. We hasten to add that this is sheer idealism. In practice, 
be prepared for a good deal of extra fiddling around before a project 
is pronounced ‘finished’. 


Amstrad’s extra commands 


The BASIC command set of the Amstrad CPC464/664 machines, the 
work of the organisation known as Locomotive Software Limited, 
can be treated under four separate headings: 
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1 The traditional general purpose commands. 
2 The extra general purpose commands. 

3 Graphic and colour commands. 

4 Sound commands 


There is little point in dealing in great detail with traditional general 
purpose commands because most readers will already be familiar 
with them. The commands which control colour, graphics and 
sound are treated as separate subjects in later chapters. We shall 
tend to concentrate here on a few of what we have called, in (2) 
above, the extra general purpose commands. Perhaps we should 
point out that our choice of which of them should come under the 
heading of ‘extra’ commands may be open to question. It may also 
be argued, and with some truth, that the User Instructions supplied 
with the machine provide adequate descriptions of the commands. 
Nevertheless, alternative explanations often aid understanding, 
particularly if accompanied by simple examples. 


Loop and condition structures 
A loop is a repetitive process and can be coded in BASIC in several 
ways. Whichever way is chosen, the top and bottom of a loop must 
be demarcated. To illustrate, we shall assume the following simple 
objective: 

Print out the squares of the integers 1 to 10 inclusive. 


Solution 1 


100 A=1: REM Initialising 
110 PRINT A*2 

120 A=A+1 

130 IF A<11 GOTO 110 


Line 100 prepares the starting value of the variable (called initialising). 
Line 110 is the process and is also the top of the loop. 

Line 120 increments the variable. 

Line 130 is the end of loop test. 

This works, but isn’t it awful? We have used it only as a guinea pig 
for defining a few of the common terms used in loop theory. 
Structure is virtually non-existent and the end of loop test is error 
prone if you forget to add the extra 1. It is also absurdly easy to 
make a mistake in the GOTO line. Consider what happens if we 
write GOTO 100 instead of 110. 


Solution 2 


100 FOR A=1 TO 10 STEP 1 
110 PRINT A*2 
120 NEXT 


This is much nicer. The advantage of the FOR/NEXT command is 
that initialisation, top of the loop and incrementation are handled by 
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one line. The amount of the increment can also be decided by the 
STEP part. (An increment of 1 is, of course, a default condition and 
the STEP can be omitted.) Although not part of the original three 
structures, the FOR/NEXT command is too useful to reject on these 
grounds alone. However, we should be aware that it is only capable 
of controlling the number of loop revolutions by counting. Thus we 
cannot use string variables to set up the loop parameters. With most 
BASICs, the process within the loop will always be activated at least 
once irrespective of the settings at the top of the loop. However, the 
Amstrad version of BASIC is different. The end of loop test is made 
at the top of the loop. The loop is skipped altogether if the initial 
value is greater than the end value (only with a positive STEP of 
course). Unlike other BASICs, it is also permissible to exit a FOR/ 
NEXT loop by avoiding NEXT. In which case the control variable 
will remain at its last value. Although perfectly legal, this practice is 
best avoided. Until the day arrives when a standardised version of 
BASIC is adopted, it could lead to problems when programming 
other machines. Sometimes, this is undesirable. When it is, we 
might consider the next solution. 


Solution 3 


100 A=1 

110 WHILE A<=10 
120 PRINT A*2 

130 A=A+1 

140 WEND 


This doesn’t look quite so neat as Solution 2. It requires a separate 
initialisation line to set the starting condition for A. It also requires a 
separate line for incrementation. The start of the loop is line 110 
which should be interpreted as, ‘while A remains less than or equal 
to 10, continue the process’. Thus the WHILE part of the structure 
has only one function — to define the conditions for the loop action to 
continue. The bottom of the loop is defined by the keyword WEND. 
Like the FOR/NEXT loop in Amstrad BASIC, the test is made at the 
top of the loop before the process is first executed. This ensures that 
the process is never executed at all if the value of the variable, at 
entry, violates the WHILE conditions. 

This is an important advantage of the structure and worth 
particular notice. Another advantage is the fact that the WHILE 
conditions allow the use of string variables. We could, for example, 
write the following condition: 


WHILE A$ <> B$ 


A situation often arises where a block of commands has to be either 
executed or skipped over, depending on a certain condition. The 
first thought that may come to mind is a simple IF/THEN such as: 
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Solution 1 
100 IF A=B THEN GOTO 150 


But, we have used the cursed GOTO which we have agreed should 
be avoided wherever possible. An alternative, and much neater, 
solution is to use the WHILE/WEND structure, not in its loop- 
creating role but simply to define a condition. Thus the above can be 
written more elegantly as: 


Solution 2 

100 WHILE A<>B 
TOG S eae ee is 
1208 We Sabeee4 
1 SO} ce hos Sea 
140 A=B 

150 WEND 


Note carefully that the condition must be expressed in the opposite 
way to that used in solution 1 — that is, if we want the effect to 
remain the same. In case this is not immediately obvious, note that 
in solution 1, the block of commands occupying lines 110 to 140 are 
skipped over if A=B but executed if A<>B. In solution 2, the 
lines are executed if A<>B but skipped over if A=B. Thus, they 
both produce identical actions even though, at first sight, they 
might appear different. 


Nesting 
WHILE/WEND loops, like FOR/NEXT loops, can be nested to any 
level. Here is an illustration of nesting: 


100 WHILE A=B 
FO) 8s Fas Poh 
120 St 4 Avsnses ess 
130 WHILE C=D 
DAO ene te seas ethos 
TOO S ee es SoS 
160 WEND 

TO teense scene Sees 


DOO is fern los Bhs Fs 
200 WEND 


The inner loop rotates around the lines 130 to 160. The outer loop 
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over lines 100 to 200. Be careful to ensure that every WHILE has its 
own matching WEND. 


Declarations 
Some languages, particularly those designed for structured pro- 
gramming, have provisions for declaring, usually at the top of a 
program, the type of each variable. For example, whether it is real, 
integer or string. On the other hand, traditional BASIC has always 
required the variable to be accompanied by its type-marker every 
time it is used. We all know that ‘%’ after a variable name indicates 
it is an integer, ‘$’ indicates a string and, in the absence of a type 
marker, variables are assumed to be real. However, Amstrad BASIC 
allows you to declare the type of all variables at the head of a 
program so you are saved the trouble of adding type markers 
wherever they appear in the rest of the program. You may find, as 
we did, that the User Instructions on declarations are just a shade 
obscure, so we make no apologies for offering additional 
information. 

If we write DEFSTR B at the top of a program, all subsequent 
references to variables with names BEGINNING with B are treated 
as string variables. Try this out: 


100 DEFSTR B 

110 B=“YES” 

120 PRINT B 

130 BLOGGS=“NO” 
140 PRINT BLOGGS 
RUN 

YES 

NO 


The result of the run shows that: 


1 Lines 110 and 130 are accepted by the computer without the 
usual ‘mismatch error’ appearing. 

2 Although only the variable B has been declared a string, 
BLOGGS has also assumed the role of a string. This is because ALL 
names beginning with B are treated as strings. 


It is allowable to declare more than one variable at a time: 
DEFSTR A,B,C,D 


This could also be written as a range of variables, DEFSTR A-D 

Integers and reals can also be declared in the same way (and 
subject to the same rules above) by using DEFINT and DEFREAL 
respectively. At the risk of being branded reactionaries, we advise 
against making too much use of declarations. If complete variable 
names could be declared, instead of just the first letter, then it 
would be a different matter. You could get into a terrible mess with 
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name clashes unless you are prepared to revert to the restriction of 
single letter variables only. One thing more — listings are going to 
look very strange to hardened BASIC fans when they see things like 
A=‘BLOGGS’ without the dollar sign after the A. 


Interrupt commands 


As mentioned earlier, some intriguing commandsare available which 
allow timed interrupts to be built into a program. Interrupt tech- 
niques may be unfamiliar to some readers, so they may appreciate 
some guidance over and above that given in the User Instructions. 

Assume a program is busy, churning out something within a 
FOR/NEXT loop and suddenly, without warning, an interrupt 
command is received. The program is immediately suspended -— 
perhaps frozen is the better word - and a branch is made to a 
subroutine. When the subroutine commands are completed, the 
program recommences from exactly the same point at which it was 
interrupted. Figure 1.3 may help in visualising the mechanics of 
interrupt. 






Main program 









Interrupt 
timer 






Interrupt signal 







Interrupt 
subroutine 


Fig. 1.3 


In most cases, the time spent in the subroutine is so short that a 
human will not be aware that an interrupt has occurred at all. What 
exactly the subroutine does is up to the programmer because he/she 
will have to write it but, for the moment, treat this as irrelevant. 
What concerns us in the first instance is how to arrange for the 
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interrupt signal to arrive and, more particularly, when and how 
often it should arrive. We have two options. We can arrange for an 
interrupt to occur once only, after a given time interval, or we can 
arrange for continuous interrupts to occur at regular timed intervals. 
The timing is controlled by any one of four independently con- 
trolled real time clocks, 0,1,2 and 3 and they each operate in units of 
1/50 second. 


Once only interrupts 
Use the AFTER command as follows: 


AFTER time delay, timer number, GOSUB line number 
Example: AFTER 200,2,GOSUB 10000 


This will branch to the subroutine at line 10000 after timer 2 has 
counted up to 200 (4 seconds). The timing starts from the time the 
program encounters an AFTER command. There can of course be 
more than one AFTER in a program. 


Repetitive interrupts 
EVERY time period, timer number, GOSUB line number 
Example: EVERY 5,1,GOSUB 15000 


This will keep branching to the subroutine at line 15000 at regular 
intervals of 1/10 second, using timer 1 as the counter. 


Disabling and enabling interrupts 
We must remember that an interrupt has no social graces. It just 
barges in whenever the programmed time has elapsed although it 
does have sufficient courtesy to wait until the present statement has 
finished executing. There may be certain critical sections of the 
program where an interrupt could be disastrous. Fortunately, 
Amstrad has provided us with two tiny commands which can 
override interrupts: 

DI will disable an interrupt and EI will re-enable it. So, all we have 
to do, to safeguard any particularly critical section, is to write DI at 
the top and EI at the bottom of the section. 


Finding time left 
We can find the amount of time left before interrupt occurs in any 
one of the timers by using the REMAIN command. It has the 
following syntax: 


REMAIN timer number 
Example: L% =REMAIN 2 


This will return (in L%) the remaining count left in timer 2 - the 
number of 1/50 second intervals left. If the timer was not enabled, 
the count returned will be zero. 
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Timer priorities 
If a program uses more than one timer, there may be a clash of 
interests. The priorities of the timers have been fixed as follows: 


Timer 3 has the highest and Timer 0 the lowest priority. 


Applications of interrupt 


Interrupt provides scope for your imagination. In the meantime, 
consider the following possibilities: 


1 keeping a time clock updated in one corner of the screen, 

2 acting on, or monitoring, a keyboard response. For example in a 
command-driven, rather than a menu-driven display, 

3 automatic switching between two or more different displays. 


The remaining extra commands 

Various other extra commands will be described as they become 
necessary in the course of later chapters. Further attention to them 
here would result in unnecessary duplication of text. 


Laying out a listing 


Listings should be easy to follow. This means they should also be 
easy on the eye. Below are a few hints and tips. 


Variable names 

Choose meaningful names rather than single letters even if it does 
waste a few extra bytes. Don’t be afraid to use lower case because it 
stands out well from BASIC keywords in a listing. 


Remarks 

We are often told to use REMs liberally. In general, this is good 
advice but you shouldn't overdo it. Over-indulgence in REMs could 
make the listing look more complex than it is. Blank REM lines are 
useful for separating different sections within a listing. Plenty of 
intervening white space emphasises the coding lines. Never allow a 
branch to a REM line because later, in an unguarded moment, you 
may decide to remove REM lines to save memory - with disquieting 
results. Avoid using constants within the body of a program because 
they take longer to execute than variables. They are best assigned to 
a variable at the head of a program. 


Spaces 

Spaces within command lines are, in the main, optional. Avoiding 
them merely to save work or memory is seldom worth the sacrifice 
in readability. 


Laying out a listing 


Defaults 

A study of the meta language used to describe Amstrad BASIC 
commands shows that simplified default forms are allowed in many 
cases. Avoid using a default form just to save work if, by doing so, 
the meaning becomes obscure. 


Multistatement lines 

Multiple statements, delimited by colons, under the same line 
number save a few memory bytes and shorten the overall length of a 
listing. However, too many statements crowded together does 
make a listing difficult to follow. It is better to compromise a little 
and restrict the number of statements per line to those belonging to 
the immediate subtask. 


Summary 


1 The Amstrad CPC464/664 video monitor has better resolution 
than a UHF modulator/TV. 

2 The video monitor allows comfortable viewing of the 80 charac- 
ters per line provided by Mode 2. 

3 The self-contained cassette tape unit allows higher speed loading 
and saving because of optimised signal levels. 

4 One baud is a rate of one information bit per second. 

5 Beware of trying to record on the leader tape. 

6 The CPC464 reserves two tape buffer areas in RAM. Each buffer 
is 2K. 

7 Normally, tape buffer areas are dynamically allocated only if 
they are needed. 

8 Dynamic allocation often causes long delays due to frequent re- 
arrangement of strings. 

9 It is easy, with a few programming lines, to change dynamic to 
static allocation. 

10 MEMORY &XXXxX will set the upper address limit of the BASIC 
area to &XXXX. 

11 BASIC is an interpretive language requiring re-translation dur- 
ing each RUN. 

12 Traditional BASIC was not designed with structure in mind. 
13 Originally, structured programming meant sticking closely to a 
few ‘structures’, mainly the WHILE/WEND, IF/THEN/ELSE and the 
SEQUENCE. 

14 Nowadays, we tend to use the term ‘well structured’ if a 
program listing is easy to follow and, as far as possible, free from 
GOTOs or implied GOTOs. 

15 Structured programming sacrifices efficiency in return for 
simplicity and uniformity. 

16 Avoid GOTOs but don’t go to absurd lengths to avoid them. 
17 A FOR/NEXT loop is skipped if the end value is less than the 
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initial value, with a positive STEP. However, this action is peculiar 
to Amstrad BASIC. 

18 A WHILE/WEND loop will not execute the process at all if the 
condition is false. 

19 FOR/NEXT conditions can only be set with numeric variables. 
20 WHILE/WEND conditions can be set using numeric or string 
variables. 

21 Modular programming means to design a program using 
separately testable modules. 

22 A module should have only one entry and only one exit. 

23 A ‘stub’ is a short, functionless stop-gap module, later to be 
exchanged for a proper module. 

24 General purpose modules can be used in different programs. 
25 Top-down design is when the program framework is designed 
first and the modules last. 

26 Bottom-up design is when the modules are designed first (or 
selected from a library) and the program framework afterwards. 
27 The WHILE/WEND structure can be engineered to replace the 
IF/THEN for skipping over a block of lines. 

28 To save appending type markers to variables each time they 
appear, the type can be declared once and for all with DEFSTR, 
DEFINT and DEFREAL. 

29 Declarations do not distinguish between variables which have 
the same starting letter. 

30 AFTER produces a one shot interrupt. 

31 EVERY produces regular interrupts. 

32 REMAIN gives the interrupt count left. 

33 DI and EI allow sections to be protected against interrupts. 

34 There are four interrupt timers, 0 to 3. Timer 3 has the highest 
priority. 

35 Use meaningful names on listings with plenty of white space. 
36 Never branch to a REM line. 


Subroutines and functions 





This chapter continues on the theme of structure and modular 
programming. Various peculiarities of user-defined functions and 
subroutines are discussed with advice given on their use. 


Module construction 


The term ‘module’ cropped up several times during the last chapter. 
It is time now to discuss how BASIC can be used to construct 
modules and how to link them together. In general, there are three 
ways of constructing modules, the procedure, the subroutine and the 
defined function. 


Procedures 

The procedure is the most powerful means of organising modules. 
It is also the most amenable to the concepts of good structure. Pity it 
is not available in Amstrad CPC464/664 BASIC! But then, if it is not 
available, why are we troubling to mention it at all? The reasons are 
twofold. Firstly, there is always a chance that, if the popularity of 
the CPC464/664 is maintained or grows still further, the designers 
may decide to introduce a revised BASIC, incorporating procedures, 
in an updated ROM. It is not unusual for microcomputer manu- 
facturers to fit improved versions in later production runs. 
Secondly, a brief description of typical procedure syntax may assist 
understanding of certain problems encountered in the design of 
subroutines. 

Besides knowing how to write the programming lines which form 
the module, we must know how to call it up from the main (control) 
program and also how to return to it. Typical syntax for calling a 
procedure is: 


500 PROCprocess name (x,y,z, etc) 


where x,y and z are variables to be passed to the procedure. 
The technique is known as parameter passing. 
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Assume we want to call up a procedure which adds interest of I, 
expressed as a percentage, to a capital of C pounds. We could call it up 
as follows: 


500 PROCinterest (I,C) 


This calls up a process called ‘interest’ (normally positioned at line 
numbers much further down the program) and passes two essential 
bits of information in the variable I and C respectively. Typical 
syntax for the definition of the procedure would be: 


10000 DEF PROCinterest (X,Y) 
10010 D% =100 

10020 amount=(X/D%)*Y+Y 
10030 ENDPROC 


The command ENDPROC signals the end of a process causing a 
return to the calling program — the exact equivalent of RETURN ina 
subroutine. Lines 10010 and 10020 perform the process of adding 
the interest to the variable Y but the weird thing to notice is the 
change in parameters. We called the process with the parameters I,C 
at line 500 but, in the definition of the procedure at line 10000, we 
have used the variables X,Y. We could have used the same variables 
but decided to exercise the option to use different ones. This is quite 
a valuable option because you can use any variables you like within 
the procedure but call it with a different set from outside the 
procedure. The only rule is that the order in which the variables 
appear when PROC is called are interpreted in the same order in the 
DEF PROC. Thus, in our example, I is copied into X and C is copied 
into Y. The value of this can be seen by considering the problems 
involved in designing an extensive library of general purpose 
procedures. The very nature of ‘general purpose’ suggests that we 
can have no knowledge, at the time of writing the procedure, what 
variable names will be used by a future program when the pro- 
cedure is called. The mechanism of procedures, as described above, 
should convince you that it doesn’t matter. You can use any (but 
preferably meaningful) names you like when designing the general 
purpose procedure. 


Local and global variables 

A dangerous clash of variables can occur between those used 
‘locally’ within a procedure and those used ‘globally’ outside the 
procedure. For example, the main program may have valuable 
information in variable D% which could be destroyed if one of the 
procedures happened to use D% for a different purpose. In our DEF 
PROC interest example above, D% was used to assign the constant 
100. Think how awful it would be trying to trace the bug if D% was 
used for some other purpose in the main program. We could reduce 
this danger by making an extra careful check on all variables used in 
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procedures before deciding which one to use globally. However, 
only politicians and judges are born with infallibility so it is reassur- 
ing to learn that microcomputers offering procedures in the BASIC 
repertoire often allow variables within a procedure to be declared 
LOCAL. For example, we could declare the variable D%, used in 
our example procedure, as ‘local’ by adding one extra line: 


10000 DEF PROC interest (X,Y) 
10010 LOCAL D% 

10020 D% =100 

10030 amount=(X/D%)*Y+Y 
10040 ENDPROC 


This will ensure that if D% is also used outside the procedure, its 
contents will not be trampled on by the local D% inside the 
procedure at line 10020. 

Having dealt with the merits of procedures, it is left to point out 
once again that we don’t have them yet in Amstrad BASIC How- 
ever, it has not been a waste of space because certain terms have 
been introduced which will help understanding of the problems to 
be tackled during the construction of general purpose subroutines. 


The role of the subroutine 


A subroutine is a somewhat inferior form of procedure. Superficially 
we could define a subroutine as a set of programming lines, 
terminating in the keyword RETURN and intended to be called up 
from the main program by means of GOSUB followed by a line 
number. A subroutine, like a procedure, behaves as a kind of 
‘subcontractor’ to the main program. Rather like a subcontractor in 
the building profession who specialises in, say, doors and window 
frames, a subroutine can be delegated the responsibility of pro- 
viding a specialised service such as providing the background to 
animation, drawing division lines or establishing a user-friendly 
keyboard. The advantage in real life of subcontracting is the fact that 
specialised expertise and experience can be drawn upon. It is the 
same with general purpose subroutines. Since they were, or should 
have been, written with great care, it it sensible to make use of them 
wherever possible in new projects instead of re-inventing the wheel 
each time — perhaps an inferior wheel at that! With experience, you 
will come to realise that a large range of programs, however 
complex in design and overall objective, still have a lot in common. 
They borrow each others’ subroutines because a high proportion of 
good programs are modular in design. 

Designing a new program, apart from changes in variable names, 
often entails little more than a re-arrangement of existing modules. 
Once this is realised, you may cease ‘normal’ program construction 
for a week or two in order to design, or collect from various sources, 
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a large library of subroutines. Instead of treating a new program as a 
fresh work of art to be written from scratch, it will, in the main, be a 
selection exercise. That is to say, you will search through your 
library for a set of suitable subroutines for splicing into the new 
project. 


Subroutine layout 

We have suggested, rather unkindly, that the familiar GOSUB is a 
poor relation of the procedure. The worst aspect of the command is 
the need to call up subroutines by means of a line number. For 
example, we have to write, GOSUB 10000 instead of GOSUB 
followed by a meaningful name. A GOSUB is still basically an 
unavoidable GOTO. Numbers have no mnemonic value so listings 
can sometimes be awkward to follow. In any case, there is little 
point in remembering GOSUB line numbers during program 
development because of the frequent renumbering exercises which 
are needed. There is also the problem of recognising the start of a 
subroutine within a listing. It is easy to see where a subroutine ends 
because we look for the RETURN command but there is no 
corresponding command for the beginning of one. (You will re- 
member that the start of a procedure is easy to spot because of the 
command DEF PROC.) So, if we expect listings to be followed 
easily, we should always head a subroutine with a REM line title. 
Bearing in mind that consistency is a powerful aid to compre- 
hension, try to stick to a fixed plan. For example, here is one: 


9999 REM SUBROUTINE: FIND MIDDLE 
10000. ee es 

10010. 6 8s ees 

10020 RETURN 


Although not mandatory, the REM is best given an odd line 
number, one less than the start of the actual subroutine because it 
will stand out more on a listing. The line to call the above should be 
GOSUB 10000, not GOSUB 9999 because, as recommended in 
Chapter 1, it is unwise to branch to a REM. It is also a good plan to 
use nice round numbers in thousands during the initial stages of 
development. For example, one at 10000, the next at 11000 and so 
on. However, when constructing a general purpose set of sub- 
routines, the line numbers will have no real importance because 
they will probably be changed by a RENUM command after they 
have been spliced into a program. If this is the case, it is probably 
just as well to start them all at line 10000. Since line number clashes 
are likely, any juggling about can be deferred to later when the 
subroutines are to be used. Temporarily, a fresh tape or disc can be 
used to store the renumbered versions of the subroutines for 
subsequent MERGEing into a program. 

While on the subject of line numbers, it is fair to point out that the 
practice of positioning all subroutines at the bottom of a program is 
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only to appease the concepts of structure. As a matter of fact, a 
program will execute slightly faster if the subroutines have low line 
numbers. This is because the BASIC interpreter starts searching for 
a subroutine from the top downwards. However, a listing with 
subroutines scattered untidily throughout the body of a program is 
far more difficult to follow. To some extent, we can compromise by 
still positioning subroutines at the bottom but, as far as possible, in 
order of usage. 


Separating subroutines 

Listings are much easier to read if blank lines are used to separate 
the various subsections. The single quote character (’) acts as a blank 
line as shown below: ' 


9999 REM INTEREST SUBROUTINE 
10000 20 cca hav ei 

TQO1O 5. hea ee 

10020 RETURN 

10097 ’ 

10099 REM DRAW LINE 

LOLOO % Sesraresece es 

LOVIO 03 sg 8 

10120 RETURN 


The two subroutines should be called with GOSUB 10000 and 
GOSUB 10100 respectively. 


Passing parameters 


Some subroutines are complete in themselves, requiring no help at 
all from the calling program. For example a subroutine to draw a 
line could be written as follows: 


lO0OUPRINT 2222S ab ewe eee ees ” 
10010 RETURN 


But, the ‘—’ character used for drawing the line is fixed. In a general 
purpose subroutine, it would be far better to allow flexibility in the 
choice of character by re-writing it as follows: 


10000 FOR K=1 TO 20 
10010 PRINT K$; 
10020 RETURN 


Now here we have the typical case of the need for parameter 
passing. The subroutine must have knowledge of K$ and this can 
only come from the calling program. We need therefore an assign- 
ment statement to precede the call such as: 
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200 K$="%” 
210 GOSUB 10000 


Parameter passing offers a rich breeding ground for bugs. It is easy 
to forget to pass the parameter, or parameters, before calling a 
subroutine. 

Many subroutines leave the result of some process. When using a 
library subroutine, it is extremely unlikely that the variable used in 
the subroutine to hold the result will be the same as the calling 
program is using. Also, it is quite probable that the subroutine will 
be called from different parts of a program and could be using a 
different result variable each time. This means that after returning 
from a subroutine, it will be necessary to re-assign the variables — a 
kind of local to global transform. For example, suppose the sub- 
routine result variable happens to be K$ but the calling program 
wants the result in F$. The subroutine call may look like this: 


250 GOSUB 10500 
260 F$=K$ 


Obviously another bug-prone point in the program. We could forget 
to insert the line at all or, equally bad, get the assignment the wrong 
way round and write it as K$=F$. Remember that the variable at the 
left of the ‘=’ sign is always the recipient of the data. Data passes 
from the right to the left of the equals sign. Every one knows this of 
course but we thought it worth a mention. 

When writing a general purpose subroutine, we naturally want to 
make it as flexible as possible so that different programs can make 
use of it. If this idea is taken to extremes, there is a danger of making 
it so fiddly to use that it never will be! For example, we could end up 
requiring nearly all variables to be passed from the main program: 
our simple subroutine for drawing a line could be expanded to: 


10000 LOCATE X%,Y% 
10010 PEN P% 

10020 FOR K=1 TO L% 
10030 PRINT K$; 

10040 RETURN 


We now have a remarkably flexible version. We can set the colour of 
the line by P%, where it is drawn on the screen by X% and Y%, the 
length of the line by L% and the character used to draw the line 
by K$. But we pay for this by having to pass five parameters before 
calling it. This is a case of flexibility carried to rather extreme limits 
and could very well put us off using it in the future. It is best to 
adopt a balanced approach towards flexibility. After all, it will be 
easy to modify existing lines or add new ones in order to satisfy a 
one-off use. 


Passing parameters 


Entering and leaving subroutines 


Remember the golden rule of modular design - only one entry and 
only one exit point. A subroutine is a module so this rule must be 
preserved in the interest of good structure. This means that we must 
only enter it at the starting line and, more importantly, leave it by 
the normal RETURN command. It is sometimes tempting to jump 
out of a subroutine before the natural end, either to save time or to 
save a few programming lines. Resist the temptation because, apart 
from anything else, it could be the very devil to debug should things 
go wrong. If it is necessary to skip a number of lines then it is the 
lesser of two evils to resort to a GOTO, providing it is going to the 
RETURN line at the end of the subroutine. Alternatively, use the 
WHILE/WEND method of skipping which was described in 
Chapter 1. It is also bad practice to have two different entrance 
points to a subroutine. It may be efficient in certain circumstances 
but it is not good structure. 


Subroutine nesting 


A subroutine can call on another subroutine to handle part of the 
task, analogous to a subcontractor employing another subcontractor. 
The technique is known as nesting because one subroutine nestles 
inside the other. In fact the process of nesting can, in theory, 
increase without limit. Figure 2.1 illustrates the flow paths of a 
three-nest (three-level) system. 

However, there is a practical limit to the number of subroutines 
which can be handled in nest form. The limit arises because of the 






Subroutine Subroutine ubroutine 
1 2 3 





Fig 2.1 
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need to store the return addresses of each subroutine. To under- 
stand the problem, consider what must happen when we write: 


200 GOSUB 10000 
21D Sos ees 


The subroutine must return to line 210 so the computer must store 
the address of the return line (or the return statement if there are 
more than one on the same line) before the call is made. If the 
subroutine calls another nested subroutine, then its return must 
also be stored. Consequently, if we have a nest of 12 subroutines 
then the computer must keep a record, in the right order, of all 12 
return addresses. The area of RAM used to keep track of the return 
addresses is called the stack. The stack is organised as a Last-In-First- 
Out or LIFO memory. The return address of the innermost sub- 
routine which was stored last must be the first one to be drawn out 
from the stack. The BASIC programmer is quite unaware of these 
stack operations because they are carried on unseen in the back- 
ground. The first indication of something wrong is the sudden 
emergence of the disconcerting error message ‘memory full’. This 
may come as a surprise because the programmer may be confident 
that there is plenty of memory left. The cause may be due to stack 
overflow which can come about by either: 


1 Too many nested subroutines. There is only a limited area in 
RAM which is reserved for the stack. 

2 Jumping out of a subroutine with GOTO before the correct 
RETURN line. If the same subroutine is called many times within a 
loop and is exited each time before the RETURN line, the pile of 
stack addresses could mount up and up until it overflows. This 
highlights the danger of a GOTO line number outside the 
boundaries of a subroutine. 


Providing these dangers are avoided, nesting provides a powerful 
method of breaking down a complex or lengthy subroutine into 
various levels or subtasks. 


The ON GOSUB and the menu 


Many programs are menu-driven. That is to say, the program offers 
a selection of options on a display called the Menu which invites the 
operator to enter the required option number. In most cases, each 
option is handled by a separate subroutine. We therefore need a 
nice easy solution to the problem of steering the program to any one 
of several subroutine line numbers. This is analogous in electrical 
work to the single-pole multiway switch, as shown in Figure 2.2 
The syntax of the ON GOSUB is as follows: 


On variable GOSUB L1,L2,L3 etc 


The ON GOSUB and the menu 


ON N GOSUB 1000, 1500, 3000, 4200, 210 





Fig 2.2 


The subroutine returns will all be to the line following the ON 
GOSUB line. 
For example, consider the lines, 


200 ON N GOSUB 1000,1500,3000,4200,5000 
Vl) ere ate erties 


If N=1, the subroutine at line 1000 is called. If N=2, the subroutine 
at line 1500 is called, and so on. The subroutines will all return back 
to line 210. Figure 2.2 shows a simple diagram of the structure. It is 
shown in the form of a completely closed loop and appears as if all the 
RETURNS are straight back to the menu. However, when we come 
to the actual coding of the structure, it is not quite so straight- 
forward. Assuming the menu starts at line 100, the obvious solution 
is to write line 210 as, 


210 GOTO 100 


This causes all subroutines to return to the menu by leapfrogging 
via the GOTO line. This is not good structure but, in this case, we 
find ourselves in one of those rare situations where the use of a 
GOTO seems unavoidable. 

The example of the menu is a perfect example to illustrate the 
concepts of a main or ‘control’ program, the modules to be con- 
nected to it and the use of provisional stubs which we introduced in 
Chapter 1. The control program will consist of a few initialisation 
lines for, say, setting the mode, assigning constants and dimen- 


33 


34 


Subroutines and functions 


sioning arrays (if any). This can be coded first and provisionally 
checked out by inserting short subroutine stubs in place of the 
proper variety. The stubs could take the form of one-line messages 
such as ‘Subroutine 1’, ‘Subroutine 2’ etc. The control program can 
then be tested out by selecting each option and ensuring that there 
is a smooth return to the menu. The proper subroutines can then be 
selected, or designed at leisure one at a time, and inserted in place 
of the stubs. In this way, the program can be built up, and tested, in 
stages and with confidence. 

Before leaving this subject, we must point out that programming 
menu options is not the only use which can be made of the ON 
GOSUB, As mentioned previously, it can be used wherever there is 
a need to select one from many subroutines. 


User defined functions 


The term function is used with a variety of meanings, depending on 
both the context and academic level of the text. Mathematicians, 
especially those of lofty calibre, write with almost indecent enthu- 
siasm on the subject of functions and are happy to devote an entire 
chapter to what they describe as a ‘provisional’ definition. It is 
sufficient for our purpose to consider a function as something which 
accepts an input variable (or variables) and produces an output 
dependent on the variable. All BASICs, including the Amstrad 
version, offer a selection of commonly used functions such as 
SIN(X), COS(X), EXP(X) etc. For example, we input (supply) the 
variable X and out comes the function SIN(X) or we input the 
variable Y and out comes the function SIN(Y). 

It is impractical for any BASIC interpreter to include more than a 
handful of these standard functions. Even if it was practical, there 
will still be a need for special non-standard functions peculiar to the 
demands of a particular program. To satisfy these needs, two 
commands are available, one to define your own special function 
and one to call on the function whenever needed. 


To define the function 

DEF FNname(formal parameters)=expression 

To use the function 

FNname(actual parameters) 

The term ‘parameters’ can be taken to mean the variables used in 
the function. Why distinguish between formal and actual para- 
meters? The reason is that the parameter names to be passed when 


the function is used need not necessarily be the same as those used 
when the function was defined. 


User defined functions 


To illustrate, assume we want a special function X*2+4 and we 
‘want to name it ‘test’. We would define the function as follows: 


DEF FNtest (X)=X*2+4. 


Note that X is a formal parameter and indicates that one must be 
supplied. The function generated is X*2+4. Once you have written 
this line, it is always available for use elsewhere in the program. For 
example, if we later write, 


Z=FNtest(Y) 


then Z will contain the value of Y*2+4. 


Syntax variations and scope 

The defined function is a powerful and highly flexible command but 
not the easiest one to understand. We must confess that we found 
the User Instructions, which arrive with the machine, a shade on 
the skimpy side. It may be that some readers also feel the same and 
may appreciate the more detailed treatment which follows. 

The first point to grasp is that the DEF FN command must come 
before it can be used by the FN command and, furthermore, it must 
occur outside a program loop. If an FN command is used before the 
DEF FN has executed, you will get the error message ‘Unknown 
user function’. The best way to be sure about what can be done and 
what cannot be done is to study examples under the following 
headings. 


Naming the function 


The name of the function is subject to the same rules that apply to 
the naming of ordinary variables. That is to say, we can use single 
letters or meaningful names with either upper or lower case 
characters. Fortunately, a function name and the same name given 
to a variable elsewhere in the program will not conflict because they 
are treated by the interpreter as different. 


Use of actual parameters 

The variable used as an actual parameter when calling on the 
function need not be the same as the one used during its defi- 
nition. Suppose for example the definition was 


DEF FNsum(S)=S*3 
The formal parameter is S but we could call on the function by 


using FNsum(T) in one part of the program and FNsum(volts) in 
another. 
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Using constants 

These can appear in both the definition and when it is called. The 
following couple of lines, together with result of the RUN, are for 
illustration: 


100 DEF FNtest(X)=X*2+8 
110 Z=FNtest(5) 

110 PRINT Z 

RUN 

33 


Using FN 

Once the function has been defined with DEF FN, we can use FN 
anywhere and at any time, just like the normal built in BASIC 
functions. We could, for example, have saved one of the above lines 
by using PRINT FNtest(5) instead of first assigning the function to 
Z. 


Complex functions 
The actual function can be quite complex and can include standard 
functions and even other defined functions. 


100 DEF FNfirst(X)=X+4 

110 DEF FNsecond(Y)=Y*2+FNfirst(3) 
120 PRINT FNsecond(4) 

RUN 

23 


If this seems a bit bewildering, substitute the constants into the 
equations and confirm that the arithmetic performed is actually 
4°24+3+4=16+7=23. 
As the following example shows, a function can reach mind- 
bending proportions: 


DEF FNcomplex(G)=SIN(G+.03)+EXP(G)+FNtest(3) 


Using global variables 
When defining a function, it is allowable to include other variables 
as well as the formal variety. For example: 


DEF FNtest(F)=SIN(F)*] 


J is the global variable and is quite legal, providing of course that it 
has previously been assigned. 


Local and global variables 

The formal parameters used in the definition are different entirely 
from global variables which happen to share the same name. The 
advantage of this is that, when writing the function definition, we 
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need not trouble too much about the letters or names we choose for 
formal parameters because the globals are protected. The following 
program illustrates: 


100 X=67:Y=6 
110 DEF FNtest(X)=X+4 
120 PRINT FNtest(Y) 
130 PRINT X,Y 

RUN 

10 

67 6 


Note that, in spite of the fact that X is used as a global variable in line 
100 and as the formal parameter in line 110, the global value is 
protected. The RUN provides the proof. 


Formal parameters 

The examples given so far have used only one formal parameter. 
However, there is no limit, within reason, to the number of them 
providing they are separated by commas. For example: 


100 DEF FNpythag(X, Y)=SQR(X*2+Y*2) 
110 PRINT FNpythag(3,4) 

RUN 

5 


Students of elementary trigonometry will note that ‘pythag’ is an 
apt choice for the function name. 


String functions 


All examples so far have been concerned with purely numerical 
operations. The formal parameters and the variables to the right of 
the equals sign have been free of string variables. Although the 
main purpose of the defined function is to satisfy mathematical 
needs, it is also capable of handling string functions. However, we 
must abide by the following rule: 

If the result is string form then the name of the function must also 
be string form — the $ type marker must be appended. As a simple 
example, 


DEF FNtest$(X)=LEFT$(K$,X) 
Note the $ sign in the function name. The formal parameter X is 


numeric. 
To prove that this is valid, study the following: 
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100 K$=”“ABCDEFGH])”” 

110 DEF FNtest$(X)=LEFT(K%,X) 
120 PRINT FNtest$(4) 

RUN 

ABCD 


We realise that the above will be criticised on the grounds that it is a 
roundabout, even silly, way to print out the first four characters of a 
string. All we can say in defence is that simple examples are the 
best, even if they are of limited value in practice. 


Functions versus subroutines 


Subroutines and functions are similar inasmuch as they are both 
modular in form and can be called up or used anywhere in a 
program. There are times when it may be difficult to decide whether 
to use a subroutine or a defined function. The following summary, 
showing their contrasting properties, may help: 


1 A subroutine can extend over many lines. A defined function is 
limited to one line. 

2 Global variables are protected if their names match the formal 
parameters local to a defined function. There is no corresponding 
protection built in to the subroutine structure. 

3 A call with GOSUB cannot pass parameters but they can be 
passed with a call to a defined function and, in addition, a value is 
passed back. 

4 Strings can be handled by a defined function although they were 
not really intended for the task. 

5 Defined functions can be called by name whereas subroutines 
can only be called by line number. 

Defined functions are ideally suited for handling purely mathe- 
matical expressions. They are intended for extending the range of 
functions beyond those offered by the BASIC interpreter. Used in 
this way, they are more efficient than subroutines. 


Building and maintaining a library 


We have frequently mentioned that a collection of subroutines and 
defined functions can provide a valuable source of building bricks 
for insertion into future programs. From now on, we shall refer to 
the collection as a ‘subroutine library’ even though it may include 
defined functions. The question now arises as to the form in which 
such a library is kept. For example, do we just keep them all on 
paper in the form of a pile of listings? If you are the energetic type 
and positively enjoy key-bashing, this is probably the most straight- 
forward way. But if, like us, you find unnecessary spells at the 


Building and maintaining a library 


keyboard so much waste of time and effort, you will prefer a more 
subtle and certainly less arduous approach. 
There are two separate issues involved: 


1 Which method do we choose for saving tested subroutines on 
tape or disc? 

2 How do we splice subroutines from the library into a future 
program? 


Saving under separate names 

As each subroutine is written, they can be saved to tape under their 
own name. We then end up with a collection of separate sub- 
routines, any one of which can be loaded back as needed. There is 
nothing wrong with this, apart from the fact that the library could 
eventually become unwieldy. Besides, you could run out of names! 
Many of the subroutines, even the most useful and often required, 
may be very short — in fact some may even be ‘one-liners’. The 
library could grow into a cumbersome affair unless distributed over 
a number of separate tapes. Even so, it takes time to locate the 
wanted subroutine if it was recorded well down the tape length. 
There is also the problem of modifications to a subroutine in the 
light of use. No subroutine can ever be pronounced perfect because, 
in the light of experience, additional lines or changes within a line 
may be indicated. Think of the problems which could arise if the 
subroutine is even a few characters longer than the original and you 
re-record it back in its old place. Ten to one, you will over-record on 
the following subroutine unless you had previously taken the 
precaution of spacing them well apart from each other. 


Saving a block of subroutines 


You may find it more convenient to collect a number of subroutines 
together and save them under a block file name. It is almost 
standard practice to place subroutines at the bottom of the program. 
To leave plenty of line room above for the main or calling program, a 
subroutine block should start at about 10000. When loaded and 
renumbered, the listing format might look like this: 


10000 REM SUBROUTINE 1 
LOOLO. jee 260%, 0-3. 0) a8 

TOO20 wires aie gine eee: 

10030 RETURN 

10040 ’ 

10050 REM SUBROUTINE 2 
10060.......... 
10070.......... 

10080 RETURN 

10080 
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etc etc etc 


There may be ten or more subroutines in a block so it is unlikely 
they would all have been programmed at one sitting. Let’s assume 
you intend to write one subroutine at each keyboard session. The 
block can be built up using the following steps: 


1 Starting (provisionally) at line 10000, construct and test the first 
subroutine. 

2 Save it on tape under a group name, say, LIBRARY1 - before 
switching off! 

3 To begin next session, load LIBRARY1 back again. 

4 Construct and test the second subroutine using line numbers 
following on from the end of the last one. 

5 Renumber again from 10000 onwards and save the lot on tape 
under the same group name LIBRARY1. 


Proceeding in this fashion, you will eventually have a tape with a 
number of subroutines all strung together and, as far as loading 
back is concerned, is one ‘program’ named LIBRARY1. How many 
subroutines you group together under one file name is your own 
choice but it is better to reserve one tape for LIBRARY1 even if there 
is plenty of tape to spare. When you have decided that enough is 
enough for LIBRARY1, tidy it up by renumbering from 10000 
onwards and take a couple of copies on each side of the tape. 
Finally, write on the cassette card, or in a Tape Register book, the 
names of the subroutines on the tape. Although we have assumed 
you are using cassette tape, the above suggestions still hold good for 
disc. 


Splicing subroutines into programs 


It is all very well having LIBRARY1 (or LIBRARYn) on tape or disc 
but there is still the problem of picking out the ones you want for a 
particular project. A simple solution, but not the most elegant, is to 
first load a complete library tape into an empty computer, whether 
or not you need all the subroutines or not. Since the line numbers 
occupied will be 10000 and below, there is plenty of line room above 
for developing the main program. The subroutines you don’t want 
can be erased by using the DELETE command, either immediately 
or when the program is finished. One little tip regarding renumber- 
ing; as the program develops, avoid the tendency to renumber all 
lines until the program is finished. As soon as you renumber, the 
subroutines lose the old line numbers which may have become 
familiar. This increases the possibility of calling a subroutine with 
the wrong line number. If you must renumber (because there are no 
vacant line numbers) the best way is to take advantage of the highly 
versatile RENUM command available. For example, when there 
comes a need to renumber, proceed as follows: 


Splicing subroutines into programs 


First use RENUM 
This renumbers all lines, including the subroutines, starting at line 
10 and proceeding with increments of 10. 

Then note the line number where the subroutine block starts. 
Assuming for the moment it is 1300, we can now write: 


RENUM 10000,1300,10 


This will push the subroutine block down to its familiar position at 
10000 onwards but leaving the program lines above it untouched. 


Using the MERGE command 


An entirely different approach to the problem of splicing sub- 
routines is to make use of the MERGE command. (See Chapter 8, 
page 27 of the User Instructions). There is an important difference 
between LOAD and MERGE. When we LOAD from tape, all 
existing programs and file pointers etc are destroyed - the new 
program is located in virgin RAM. Subject to a certain proviso, 
when a program or block of subroutines is MERGED, it is loaded on 
to the end of any program already existing in RAM. The proviso is 
that the line numbers of the program to be merged must be higher 
than those of the existing program, otherwise the line numbers will 
clash. This should not cause any trouble when merging subroutines 
because they should already be allocated high line numbers. 

The advantages of merging are best appreciated when some 
routines from LIBRARY1 and some from LIBRARY2 are required. If 
you have decided to keep every subroutine or function on tape 
under separate file names, then the use of MERGE is almost 
mandatory. It often entails much juggling around with deletion, 
renumbering and merging but, with a bit of practice, it becomes 
second nature — we hope! 


How subroutines will be presented 


Description of subroutines in this, and subsequent, chapters will be 
presented in the following manner: 


Module name: 

Listing: this will include, 

1 the subroutine listing 

2 a short calling program for passing example parameters 


Objective: what the subroutine actually does. 
Variable names: a list of the variables and their functions used within 
the subroutine. 
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Preparation before calling with GOSUB: list of variables, if any, which 
must be assigned before calling. 

Action required after RETURN. 

How it works: a brief description of the module. 

Example calling program: these head the listings, are primitive and 
free from user-friendly techniques. To have included them would 
have contributed little - except obscurity. 

Line numbers: all subroutines and defined functions will start from 
line 10000. Example calling programs will start from line 10. 


Summary 


1 The Amstrad CPC464/664 does not support procedures so mod- 
ules must be constructed from subroutines or defined functions. 

2 A local variable is one accessed only in the subroutine itself. 

3. A global variable is one which is accessed anywhere within a 
program. 

4 A subroutine behaves as a subcontractor to the main program. 
5 Always use a REM line at the top of a subroutine but never call it 
by this line. 

6 It is a convention, not a rule, to position subroutines at higher 
line numbers than the main program. 

7 Parameters are values or variables which may need passing 
before a subroutine is called. 

8 Subroutines should have only one entry and one exit point. 

9 Never jump out of a subroutine before the normal RETURN. | 
10 Nesting is when a subroutine calls on another. Subject to stack 
limitations, nests can be constructed to any level. 

11 The stack is a LIFO memory system. The last data to enter is the 
first to be retrieved. 

12 The ON GOSUB command can be visualised as a single pole- 
multiway switch. It is an obvious choice for menu work selection. 
13. When developing a menu-controlled program, insert stubs 
pending their replacement by actual subroutines. This allows test- 
ing in stages. 

14 User defined functions extend the range of functions beyond 
those offered by BASIC. 

15 Formal parameters are variable names used within the defined 
function. 

16 Actual parameters are those passed when calling with FN. 

17 All formal parameters are local to the defined function and will 
not corrupt global variables of the same name. 

18 Defined function names are distinguished from similar global 
names. 

19 Defined functions can use global in addition to formal para- 
meters but they are not protected. 

20 A defined function can include other defined functions as well 
as the normal BASIC variety. 
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21 String functions are allowed but will not be widely used. 

22 If the result is a string function, the function name must have 
the $ type marker. 

23 Defined functions can only extend over one line number. 

24 Library subroutines can be saved under separate names or 
bundled together as a block under one name. 

25 Programs can be developed by first loading in a library tape. 
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General purpose 
subroutines 


This chapter is intended to be used as a reference source of general 
purpose subroutines. We have found that one or more of these 
subroutines are needed in nearly every program we develop. For 
example, it is often necessary to obtain numerical input or a menu 
selection from the user. In each case the computer must be given 
instructions to reject out of range inputs without breaking out of the 
program. These type of subroutines are usually called many times 
from within the body of the program. In fact, it is often worthwhile, 
before embarking on a programming project, to load a few of the 
more commonly used ones into memory. 


Difficulties of classification 


Most subroutines can be categorised and described under a descrip- 
tive group heading. Others, like those in this chapter, defy classifi- 
cation and subsequently attract the rather derogatory label ‘general 
purpose’. Although most of them are simple in design they are still 
useful either as stand-alone subroutines or employed in a subordi- 
nate capacity as dependent subroutines. We shall find that many of 
the more complex examples described in later chapters may, in turn, 
call on one or more of these general purpose subroutines. 


Protection of global variables 


It is worth repeating the warning given in the previous chapters that 
the BASIC subroutine structure has no inbuilt protection against 
corruption of variables used globally. That is to say, you cannot 
declare subroutine variables as LOCAL. This is why you should 
always scrutinise the ‘Variables used’ list to ensure there is no 
unwanted clash of names when you are developing a program. If 
there is, you must choose other variable names in the program or, 
alternatively, change those we have used in the subroutine. 


Protection of global variables 


Customising 

We have tried to write the subroutines in a straightforward, easy to 
read manner without resorting to clever tricks merely to save a few 
bytes. Experienced readers should find little difficulty in applying 
surgery in order to economise on RAM space or to customise for a 
particular application. 


Subroutine 3.1 Hold display 


10 REM EXAMPLE: HOLD DISPLAY 

20 CLS 

30 PRINT"This display held until key is pressed" 
40 GOSUB 10000 

so CLS 

60 END 

7O ° 


80 

9999 REM HOLD DISPLAY SUBROUTINE 

10000 PRINT"Press any key to continue" 
10010 K$="" 

10020 WHILE K$="" 

10030 K#=INKEYS 

10040 WEND 

10050 RETURN 


Objective: To halt a program until a key is pressed. 

Variable names: K$=variable holding ASCII value of key. 

Action required before calling with GOSUB: None. 

How it works: The ‘press key’ prompt is displayed and K$ cleared to 
null string. The WHILE/WEND loop is relinquished only when the 
INKEY$ command detects a key press. 

Example calling program: Displays the message and exits after the first 
key press. 

Suggested uses: Anywhere where a halt is required. 


Subroutine 3.2 Simple time delay 


10 REM EXAMPLE: SIMPLE TIME DELAY 
20 CLS 

30 PRINT"Time delay starts now" 
40 seconds%=20:GOSUB 10000 


SO PRINT"Time delay over" 
60 END 
7a ° 


80 ° 
9999 REM TIME DELAY SUBROUTINE 
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10000 start=TIME/300 
10010 finish=start+secondsZ% 


10020 WHILE TIME/300<finish 
10030 WEND 
10040 RETURN 





Objective: To introduce a time delay. 

Variable names: TIME=the BASIC pseudo variable in units of 1/300 
second. 

start=start of delay period. 

finish=end of delay period. 

seconds% =required time delay in seconds. 

Preparation before calling with GOSUB: seconds% must be set to 
required time delay (in seconds). 

Action required after RETURN: None. 

How it works: Line 10000 — the instantaneous time, calculated in 
seconds, is first assigned to start. 

Line 10010 — the desired finishing time is assigned to finish. 

The WHILE loop repeats until TIME catches up with finish. 
Example calling program: A fixed time delay of 20 seconds is used 
before calling the subroutine. Screen messages note start and 
finish of this delay. 

Suggested uses: 

1 Holding a display for a fixed period of time. 

2 Slowing the execution of a program. 


Subroutine 3.3 Print timed message 


10 REM EXAMPLE: PRINT TIMED MESSAGE 
20 CLS 

30 M$="The tea is too hot" 

40 seconds%=5 

50 XCOORD%=7: YCOORDZ=10 

60 GOSUB 10000 

70 CLS 

80 

90 ' 

100 ' 

9999 REM TIMED MESSAGE SUBROUTINE 
10000 start=TIME/300 

10010 finish=start+seconds% 

10020 LOCATE XCOORD~%, YCOORD% 
10030 PRINT M$ 

10040 WHILE TIME/300<finish 

10050 WEND 

10060 RETURN 





Subroutine 3.3 Printed timed message 


Objective: To display a message for a specified time at a specified 
screen position. 

Variable names: seconds% =required display time period. 

TIME= pseudo variable in units of 1/300 second. 

start=start of delay period. 

finish=end of delay period. 

M$=text message in string form. 

XCOORD% =screen position X coordinate. 

YCOORD% =screen position Y coordinate. 

Preparation before calling with GOSUB: 

seconds% must be set to message display time in seconds. 
XCOORD% must be set to required X screen coordinate. 
YCOORD% must be set to required Y screen coordinate. 

Action required after RETURN: None. 

How it works: Line 10000 — the instantaneous time, calculated in 
seconds, is first assigned to start. 

Line 10010 — the desired finishing time is assigned to finish. 

The message, M$, is displayed at the specified screen position. 
The WHILE loop repeats until TIME catches up with finish. 
Example calling program: A fixed time delay of 5 seconds and X and Y 
coordinates of 7 and 10 respectively are assigned, together with an 
example message in M$. 

Suggested uses: Displaying error messages for fixed periods of time 
where an operator response is not required. 


Subroutine 3.4 Centralise text 


10 REM EXAMPLE: CENTRALISE A SHORT TEXT 
20 REM MESSAGE ON THE SCREEN 

30 MODE 1:CLS 

40 columnsZ=40: YZ=12 

50 M$="This is central" 

60 GOSUB 10000 

70 END 


80 

90 ' 

9999 REM CENTRALISE TEXT SUBROUTINE 
10000 startZ=(columnsZ-LEN (M$) ) /2 
10010 LOCATE start%,Y~% 

10020 PRINT Mt 

10030 RETURN 


Objective: To print a message which, irrespective of length, is 
centralised horizontally on the screen and at a desired vertical 
position. 

Variable names: Y% =vertical coordinate. 

columns% =screen width. 
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M$=holds message. 

start% =leftmost character position. 

Action required before calling with GOSUB: Message must be assigned 
to M$. 

Columns% must be set to screen width for the mode in use. 
Action required after RETURN: None. 

How it works: Line 10000 performs the arithmetic for centralising and 
the following line takes care of the vertical position. The message 
must not exceed one screen line. 

Example calling program: Assigns an example message to M$ and 
constants. 

Suggested uses: Useful as a general cosmetic aid, symmetrical titles on 
Option pages etc. 


Subroutine 3.5 Elapsed time clock 


10 REM EXAMPLE: ELAPSED TIME CLOCK 
20 WINDOW#HO,1,40,4,25 

30 WINDOW#H#1,1,40,1,3 

40 CLS:CLS#1 

SO LOCATE#1,1,2 

60 PRINT#1 ,STRINGS (40, CHR$ (154) ) 
7O SZ=0:MZ=0:HZ=0 

80 EVERY 50,0 GOSUB 10000 

90 WHILE 1<>2 

100 PRINT"Program executing" 

110 WEND 

120 END 

130 ' 

140 

150 REM UPDATE CLOCK SUBROUTINE 
10000 S%=S%+1 

10010 IF SZ=60 THEN MZ=MZ+1:S2%=0 
10020 IF MZ=60 THEN H%Z=H%+12MZ=0 
10030 IF H%Z=24 THEN HZ=0 

10040 LOCATE#1,15,1 

10050 PRINT#1,"Time elapsed " USING "##: ##: ##"5HZ, 
MZ,S% 

10060 RETURN 





Objective: To update an on-screen clock with the elapsed time. 
Variable names: 

S% =number of seconds. 

M%=number of minutes. 

H% =number of hours. 

Preparation before calling with GOSUB: The three variables, H%,M% 
and S% must be initialised to zero. 


Subroutine 3.5 Elapsed time clock 


Action required after RETURN: None. 

How it works: The subroutine is called every second by the EVERY 
interrupt command. It then updates the variables S%, M% and H% 
as necessary and displays the elapsed time on the screen in hours, 
minutes and seconds. The updated display is placed in a separate 
window (text stream #1) and makes use of the PRINT USING 
command. 

Example calling program: Two test windows are set up with arbitrarily 
chosen dimensions, one for the purposes of a program execution 
area (text stream #0) and the other for a clock display window (text 
stream #1). Both windows are cleared and a line, consisting of 40, 
CHR$(154) graphic characters is used to denote the limits of the 
windows on the screen. The subroutine is called every second, 
while the simple WHILE/WEND loop is executing a dummy 
program. 

Suggested uses: Updating an elapsed time clock while any program is 
being executed. The subroutine can also be used as an actual time 
clock, the only difference being the setting of H%, M% and S% to 
the hour, minute and second respectively of the actual time. These 
can be initialised by input statements. 

Notes: The clock keeps reasonably good time — in fact as good as the 
average mechanical clock over the likely period the computer is 
powered up. 


Subroutine 3.6 Numerical input validation 






















10 REM EXAMPLE: UNIVERSAL 
20 REM NUMERICAL INPUT VALIDATION 

30 CLS 

40 PRINT"Enter any number (1-10)" 

50 low=1:high=10: typeZ=0 

60 GOSUB 10000 

70 valid=K 

80 PRINT"The number returned is";valid 

90 END 

100 ‘ 

110 

9998 REM NUMERICAL INPUT VALIDATION 

9999 REM SUBROUTINE 

10000 INPUT K 

10010 IF type%=0 AND K<>INT(K) THEN PRINT" Input no 
t an integer":GOTO 10000 

10020 IF K<low OR K>high THEN PRINT"Input out of r 
ange":GOTO 10000 

10030 RETURN 








Objective: To input a number at the keyboard within a given range 
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and of a given type. Only if the input is of the correct type and range 
will it be accepted, otherwise, a message is displayed and input re- 
prompted. 

Variable names: type%=a flag for defining the type of variable 
(integer=0:floating point=1). 

high=range maxima. 

low=range minima. 

K=validated output 

Action required before calling with GOSUB: Assign values to low, high 
and type%. 

Action required after RETURN: Assign K to the variable of your 
choice. 

How it works: Reads the input number into K. Line 10010 checks if 
type% flag is set to integer input. If it is, and K is not an integer, the 
input is rejected, a message ‘Input not an integer’ is displayed and 
further input requested. Line 10020 checks whether K is between 
the setting of low and high and, if not, the message ‘Input out of 
range’ is displayed, prior to a further input prompt. If the ENTER 
key is pressed before entering data, the input is assumed to be zero. 
Example calling program: Validates input to an integer within the 
range 1 to 10. 

Suggested uses: Wherever numerical input of incorrect type or range 
must be rejected. 


Subroutine 3.7 String input validation 


10 REM EXAMPLE: STRING INPUT VALIDATION 
20 CLS 

30 PRINT “Enter any string" 

40 caseZ=1:size%Z=10:GOSUB 10000 

SO wanted$=K$ 

60 PRINT"Returned string is: "s;wantedt 
790 END 

BO ’ 


90 
9998 REM STRING INPUT VALIDATION 


9999 REM SUBROUTINE 

10000 K$="" 

10010 WHILE K$="" 

10020 INPUT K% 

10030 WEND 

10040 IF caseZ=1 THEN K$=UPPERS$(K#) ELSE K$=LOWERS 
(KS) 

10050 IF LEN(K$) >sizeZ% THEN K#=LEFT$(K#,sizeZ) 
10060 RETURN 





Objective: Accepts a string input entered in either upper or lower 


Subroutine 3.7 String input validation 


case but converts it, if necessary, to a desired case. Inputs in excess 
of a desired number of characters are rejected, so also is the null 
string input. 

Variable names: case% = flag for desired case (1=upper case, 0=lower 
case). 

size% =number of characters allowed. 

K$=validated string input. 

Action required before calling with GOSUB: Assign values to case% and 
size%. 

Action required after RETURN: Assign K§$ to the variable of your 
choice. 

How it works: A WHILE/WEND loop continues while the input is 
null string. Line 10040 converts, if necessary, to the desired case. 
Line 10050 checks the number of characters and chops the string if 
the string length exceeds size%. 

Example calling program: Line 30 supplies the prompt and the 
following line defines upper case by setting case% to 1. Line 40 also 
sets, size%, at 10 characters. On return from the subroutine, the 
content of K$ is assigned to the (assumed) variable, wanted§. 
Suggested uses: can be used in most circumstances requiring string 
input obeying certain restrictions. 


Subroutine 3.8 Get yes/no response 


10 REM EXAMPLE: GET YES/NO RESPONSE 

20 CLS 

30 PRINT"Do Elephants have ears ?" 

40 GOSUB 10000 

50 IF K#="Y" THEN PRINT"response is yes" ELSE PRIN 
T"response is no" 

60 END 

70 ° 

80 

9999 REM GET YES/NO RESPONSE SUBROUTINE 
10000 PRINT"Enter your response (Y/N)" 
10010 K$="" 

10020 WHILE K#<>"Y" AND K$<>"N" 

10030 K$=INKEYS 

10040 K#S=UPPERS (K$) 

10050 WEND 

10060 RETURN 





Objectives: To accept either Y,y N or n but reject all other inputs. 
Lower case input is converted to upper case. 

Variables names: K$=variable holding keyboard response. 

Action required before calling with GOSUB: None. 

Action required after RETURN: Assign K¢ to a variable of your choice. 
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How it works: The WHILE/WEND loop is in control until either of the 
four allowed keyboard responses are received into K§. If either n or 
y is input, line 10040 converts to N or Y respectively. 

Example calling program: Line 30 asks a question. Line 50 prints one of 
two possible messages, depending on the response from the 
subroutine. 

Suggested uses: Where any screen query demands a yes/no answer. 
The subsequent course of action would then be determined by the 
contents of a variable. 


Subroutine 3.9 Strip left 


10 REM EXAMPLE: STRIP A STRING TO THE 
20 REM LEFT OF A CHOSEN CHARACTER 

30 CLS 

40 M%="AJ Bloggs:3 Hill st,Merseyside" 
SO marker$=";" 

60 GOSUB 10000 

70 starboard$=Ks 

80 PRINT"The tull string is:” 

90 PRINT M¢ 

100 PRINT"The required string is:" 
110 PRINT starboards 

120 END 

130 

140 ' 

9999 REM STRIP LEFT SUBROUTINE 

10000 FZ=INSTR (M$, marker$) 

10010 K#=RIGHTS (M$,LEN (M$) -F%) 

10020 RETURN 





Objective: To strip all characters from a string which appear to the 
left of a chosen character. 

Variable names: F%=position within the string where the chosen 
character appears. 

M$=the full string before stripping. 

marker$=the character from which the stripping is to begin. 
Action required before calling with GOSUB: Assign M$ and marker$ 
Action required after RETURN: Assign K$ to a variable of your choice. 
How it works: Line 10000 places the number of characters to be 
stripped off into F%. That is to say, the number of characters there 
are before the marker is reached, starting from the left of the string. 
Line 10010 performs the actual stripping. 

Example calling program: A typical string is displayed in full and the 
marker character is set to be “:’”. On return from the subroutine, the 
stripped string is returned in K$. This is then copied to starboard$ 
and displayed. 
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Suggested uses: To strip off forenames from surnames or names from 
addresses, etc etc. 


Subroutine 3.10 Strip right 


10 REM EXAMPLE: STRIP A STRING TO THE 
20 REM RIGHT OF A CHOSEN CHARACTER 

30 CLS 

40 M$="AJ Bloggs:3 Hill st,Merseyside”" 
50 marker$=":" 

60 GOSUB 10000 

70 ports=K$ 

80 PRINT"The full string is:" 

90 PRINT M$ 

100 PRINT"The required string is:" 
110 PRINT ports 

120 END 

130 ' 

140 

9999 REM STRIP RIGHT SUBROUTINE 

10000 FZ=INSTR(M$,marker$)—-1 

10010 K#=LEFT$ (M$,F7) 

10020 RETURN 





This subroutine is identical in all respects except that left is replaced 
by right. Line 10010 uses LEFT$, rather than RIGHTS to perform the 
strip. 


Subroutine 3.11 Code and decode date 


REM EXAMPLE: DATE CODE & DECODE 
CLS 

WHILE LEN (D#)<>8 

INPUT"Enter date (DD:MM:YY) "3;D$% 
WEND 


REM CODE DATE FOR STORING & SORTING 
date$=D$: flag%=1:GOSUB 10000 
D$=rev$ 

PRINT"The coded date is ";D¢ 


REM DECODE DATE FOR PRESENTATION 
date$=D$: f1ag%=0:GOSUB 10000 
D$=rev$ 

PRINT"The decoded date is ";D¢ 
END 
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170 ° 

180 ° 

9999 REM CODE & DECODE DATE SUBROUTINE 

10000 IF flag%=1 THEN P$=""inZ=4 ELSE P$="2"3n“Z=3 


10010 rev$=RIGHT$ (date#, 2) +P$+MID$ (dates ,n%,2) +P$+ 
LEFT$ (dates, 2) 
10020 RETURN 





Objective: To code and decode a date in conventional form (day: 
month:year) to/from a form suitable for sorting chronologically 
(year:month: day). 

Variable names: flag% =a variable acting as a flag which is set to 1 for 
coding and 0 for decoding. 

in% =a variable set as a character pointer within a string. 

rev$=a string variable containing either the final coded or decoded 
date. 

P$=a string variable set to either a null string, if in code mode, or set 
to a colon if in decode mode. 

date$=a string variable set to the initial date format, whether in 
coded or decoded form. 

Action required before calling with GOSUB: Set date$ to the initial date 
format. 

Set flag% to either 1 for code or 0 for decode. 

Action required after RETURN: Assign rev$ to your variable of choice. 
How it works: In date coding mode, the input data is assumed to 
have been assigned to date$ in three groups of two digits, separated 
by colons, DD:MM:YY. These correspond to day, month and the 
year respectively. The subroutine strips out the colons and reverses 
the format to YYMMDD. The date is then in a form suitable for 
normal string sorting. 

In date decode mode, signified by flag% being set to zero, the 
reverse process is effected, ready for screen displays or hard copy. 
Example calling program: Lines 20 to 50 clear the screen and ask for 
the date in the form DD:MM:YY. 

Lines 80 to 100 set flag% to date code mode and calls Sub- 
routine 3.11 

Line 100 prints out the date in its coded form. 

Lines 130 to 140 set flag% to date decode mode and calls Sub- 
routine 3.11 again. 

Line 150 prints out the date in its original form including the colon 
separators. 

Suggested uses: When records are entered into the computer, the date 
fields can be converted to the coded format before storage. All 
operations can then be performed, including chronological sorting. 
Date decoding will only need to be used for subsequent display 
purposes. 

Notes: When using the subroutine be careful to enter leading zeros 
where necessary. For example 1:4:84 must be entered as 01:04:84. 


Subroutine 3.11 Code and decode date 


Another input validation subroutine may be justified in an applica- 
tions program to guard against this possibility. 


Subroutine 3.12 Single key validation 


REM EXAMPLE: MENU SELECTION 

REM VALIDATE A,B,C,D,E,F & G ONLY 
CHOICE$="ABCDEFG" 

CLS:PRINT"Press a key : Only "CHOICES" accepted 


GOSUB 10000 
PRINT"The Validated selection is :"SEL% 
END 


9999 REM SINGLE KEY VALIDATION 

10000 SELZ=0 

10010 WHILE SEL%=0 

10020 K%$=UPPER$ (INKEY$) 

10030 IF K$<>""" THEN SELZ=INSTR (CHOICES ,K#) 
10040 WEND 

10050 RETURN 


Objective: To accept a character from the keyboard, only if it is 
present in the string variable, CHOICE$. The character position is 
returned in a variable SEL%. 

Variable names: K$=variable receiving keyboard character. 
CHOICE$=string containing all acceptable characters. 

SEL% =variable holding the position of a validated character pre- 
sent in CHOICE$ the string. 

Action required before calling with GOSUB: Set up CHOICE$ for 
acceptable characters (numbers, letters or a mixture of both). 
Action required after RETURN: SEL% can be used to control ON 
GOSUB commands. 

How it works: Line 10020 gets the key pressed and ensures upper 
case, even if a lower case letter is entered. 

Line 10030 assigns to SEL% the numerical position of the character 
within CHOICE$. For example, if CHOICE$=“ABCDEFG” AND C 
was pressed, SEL% would contain 3. The WHILE/WEND loop 
handles the rejection of illegal keyboard entries. 

Example calling program: An example string is assigned to CHOICE$ 
and, on return from the subroutine, the number left in SEL% is the 
character position of the validated key within CHOICE$. 

Suggested uses: To restrict acceptable keyboard input to a fixed range 
of characters. This could be used say to validate a menu selection. 
Notes: The variable SEL% can be used to directly control ON GOTO 





55 


56 


General purpose subroutines 


or preferably ON GOSUB structures. The routine has the advantage 
of single key menu selection of over 9 elements by also making use 
of letters. 


Summary 


1 Global variables are not protected if used within subroutines. 

2 The pseudo variable TIME is in units of 1/300 seconds. 

3 Aclock updated by the EVERY command keeps quite good time 
over the period a computer is likely to be switched on. 

4 The date can only be sorted into chronological order if the two 
digit groups representing the day, month and year are placed in 
reverse order. 

5 In the above two-digit date groups, a leading zero must be 
present for numbers less than 10. 








Mathematical subroutines 
and defined functions 


The general aim of this chapter is twofold. Firstly, as a reference 
source of subroutines and functions which are not directly available 
in BASIC such as inverse trig and hyperbolic functions. Secondly we 
hope to show how the Amstrad CPC464/664 can be employed in 
taking the drudgery out of solving difficult equations or problems. 
Mathematics is rather an unpopular subject, and is inclined to be a 
little on the dry side for some readers. However, most medicines are 
unpalatable and, for those interested, we have chosen a small but 
representative selection of techniques to solve both polynomial 
equations and display combinations. The former uses a well known 
iterative technique known as the Bisection method and the latter 
employs a hash table. The use of a hash table is beneficial where 
repetitive checks for the inclusion of a particular item is required. In 
this way, duplicate data can easily be rejected or counted. It is 
certainly worth the time to persevere with hashing techniques since 
they can also be used in database programs for the storage and recall 
of records. 


Introduction 


To say that maths and physics covers a wide ground would be a 
gross understatement. We can only concentrate on a few areas 
which, although not of direct interest to all readers, may serve as 
guidelines for other projects. The mathematical commands on the 
Amstrad 464/664 are powerful enough to handle most complex 
equations providing care is taken to avoid common pitfalls such as 
division-by-zero, unreal roots and unexpected rounding errors. 


Equations and BASIC 


A text book equation is seldom in a form suitable for direct 
implementation in BASIC. Readers of mature age may have 
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struggled through Sylvanus P Thompson’s book ‘Calculus made 
Easy’ and still remember the passage in which he makes a tramp (an 
itinerant gentleman) refer to ‘. . . little x up in the air’. The fact that 
Y=Z* written in BASIC becomes Y=Z*X is an obvious example of a 
format change. Arguments within functions must be enclosed in 
brackets, even though they may be optional in the text book 
version. For example, COS X must be written COS(X). 


Degrees and radians 

Whilst on the subject of trig functions, it is worth pointing out that 
all arguments are assumed, by default, to be in radian measure. If 
you prefer to work in degrees (most of us do, anyway) the command 
DEG must appear somewhere. The effect of DEG lasts the life of the 
program unless it is cancelled by the command RAD, RUN or 
CLEAR. While we may acknowledge the radian to be the more 
elegant unit, the real world has always favoured the humble degree. 
It seems strange that even modern dialects of BASIC, expressly 
designed for mass appeal, continue to treat the degree as a second 
class unit by bestowing default status on the radian. 

A pi value of 3.14159265 is obtained from the keyword PI. 


Logarithmic functions 
Two log functions are available and both return values in real 
number form: 


LOG(X) returns the log to base e, where e is the base of Naperian 
logarithms. The number e is indeterminate but 2.71828 is accurate to 5 
decimal places. 

LOG10(X) returns the log of X to base 10 —- the common log. 


The exponential function 

EXP(X) returns a value, e*, where e is again 2.71828 etc. The 
function crops up in the most unexpected areas including swinging 
pendulums, radio-active decay, growth of babies and population 
statistics. It also forms an essential ingredient of hyperbolic functions. 


Inverse trig functions 

ATN(X) is the only inverse trig function directly available. However, 
we can extend the range by means of the following defined 
functions: 


1 DEF FNarcsin(X)=ATN(X/SQR(—X*X+1)) 
(For values of X less than 1) 
2 DEF FNarccos(X)=—ATN(X/SQR(—X*X+1))+PI/2 


(For absolute values of X less than 1) 
Hyperbolic functions 


These functions are not directly available but can be obtained from 
the following defined functions. They are true for all values of X: 


Equations and BASIC 


3. DEF FNsinh(X)=(EXP(X)—EXP(—X))/2 
4 DEF FNcosh(X)=(EXP(X)+(EXP(—X))/2 
5 DEF FNtanh=—EXP(—X)/(EXP(X)-+EXP(—X))*2+1 


Use of brackets 

When writing down algebraic expressions, the number of bracketed 
terms necessary can be reduced by relying on the following operator 
precedence: 


* raising to powers 

— when used to indicate a negative quantity 
* multiply 

/ divide 

\ integer division 

MOD integer modulus 

+ addition 

— subtraction 


Examples: 

3+6%5=90. 34+3°2/6+4=6. 4-18/3°2=2. 

Relying on precedence makes for efficiency in terms of memory and 
execution speed but the practice can be error prone. Unless you are 
confident with regard to the above order of operator precedence, it 
is safer and certainly makes for a more readable listing if brackets are 
used liberally. 


Binary and hexadecimal 
Decimal numbers can be expressed as a binary string by using 
BIN$. The format is: 


BIN$(decimal number,number of binary digits) 


for example, BIN$(63,16) would return the string ‘0000 0000 0011 
1111’. (We have shown this in spaced groups of four for illustrative 
purposes only.) 

A decimal number can be expressed as a hexadecimal string by 
means of HEX$. The format is: 


HEX$(decimal number, number of hex digits) 


for example, HEX$(196,4) would return the string ‘00C4’. 

In both HEX$ and BINS, if the second parameter entered is too 
small, it is ignored. For example, HEX$(196,1) would be returned as 
“C4”. 

The STR$ command can be used to convert hex back to decimal. 
For example, K$=STR$(&FF). 


Subroutines or defined functions? 
Mathematical expressions can often be implemented as a defined 
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function, rather than a subroutine. In fact, the defined function is 
tailormade for the job, offering local protection for parameter 
variables (refer back to Chapter 2). One reminder — the function 
must be defined with DEF FEN before it is called with FN. Since the 
definition need only be executed once, however many times it is 
called, it is best treated as an initialisation task and placed near the 
top of the program. 


Numerical limits 
Signed integer numbers are held in two’s complement notation and 
occupy two bytes. This restricts their range to, —32768 (2'°) to + 
32767 (215-1). The largest positive unsigned integer is 65535 (2'°—1). 
All real numbers occupy five bytes in memory, irrespective of their 
magnitude. The largest and smallest absolute real numbers, 
expressed in mantissa and power of ten exponent form, are approxi- 
mately 1.7E+38 and 2.9E—39. 


Handling simple equations 


Fortunately, the majority of equations which crop up in technology 
present little difficulty. Let’s take a simple but widely used equation 
in electronics which gives the frequency of a series resonant 
electrical circuit. It would have the following text book appearance: 


1 
2rV LC 


It doesn’t matter in the slightest if you lack a background in 
electronics and have never seen it before. The important thing is to 
examine any equation, not just this one, to see if there are certain 
values of the variables which might cause a program to crash out. 
We start by re-writing it in a form acceptable to BASIC: 


f=1/(2%PI*(SQR(L*C)) 

This is acceptable, but we should note that 2*PI is a piece of 
arithmetic which need only be done once, preferably during the 
initialisation stages. If we write, say, k=2*PI somewhere, the 
equation can now be written: 

F=1/(k*SQR(L*C)) 

We may then decide to put it into defined function form: 


DEF FNres(L,C)=1/(k*SQR(L*C)) 


The formal parameters are L and C and therefore enjoy the 


Handling simple equations 


protection offered by local status. Later, we might call the function 
with, say: 


fr=FNres(L1,L2) 


where L1 and L2 are actual parameters of global status. We could 
also pass over direct constants: 


fr=FNres(2E—1,2E—3) 


If fr was printed to 3 decimal places, we should get 7.958. 

Now for the hidden dangers. In this case, they are easy to spot. 
L or C or both can be zero in the denominator because the square 
root of zero is a real number but the machine would still throw up 
an error 11 message ‘Division by zero’ because 1/zero is meaning- 
less. Furthermore, if one of them is negative (either L or C alone), 
the result is unreal, provoking an error 5 message, ‘Improper 
argument’. If both are negative and non zero, the product of L and 
C remains real and acceptable. 


Scaling problems 


The SI system, based on the earlier MKS units, has been accepted by 
technical colleges and universities for many years. Whatever system 
is used, there will always be some units which turn out to be far too 
large or too small for practical measurement. A classic example in 
electrical physics is the SI unit called the Farad, a truly gigantic unit. 
According to one enterprising writer, the total capacitance of the 
planet Earth, treated as a perfect conducting sphere, turns out to be 
only one quarter of a Farad! In practical electronics, even the 
microfarad (one millionth of a Farad) is a relatively large unit and 
capacities of a few picofarads (one million millionth of a Farad) are 
not at all unusual. Values like these present difficulties when 
attempting to introduce user friendliness. For example, when a 
screen prompt asks for the value of capacitance, expected to be in 
the range of a few microfarads, it would be unkind to expect the 
user to input in terms of Farads. Instead, the message should be 
‘Enter capacitance in microfarads’. This is now user-friendly but 
raises problems for the program. You can get into a hopeless mess 
with units if you try to re-write equations using multiples or 
submultiple forms of the unit. The safest way is to convert all values 
received from user-friendly keyboard input into standard SI units 
and leave them in this form until all calculations are finished. As an 
illustration, consider our previous formula for series resonant fre- 
quency which, as it stands, is only true if L is in Henries (SI unit of 
inductance) and C is in Farads. A suitable request for keyboard 
input might be: 
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100 INPUT’Enter inductance in mH ”;L1 
110 INPUT“Enter capacitance in uF ”;C1 
120 LI=L1*1E—3:C1=C1*1E—6 


Line 120 converts mH to Henries and uF to Farads ready for direct 
implementation into the standard equation. Although we have 
recommended that units should remain in pure SI form throughout 
the length of the program, when the time comes to print out results, 
the units can be converted back again to more practical values. 
Thus, if the result of our equation for fr was 45000 Hz, we might like 
to print it out in KHz (1000 Hz) so we could write: 


500 fr=fr/100 
510 PRINT“The resonant frequency is “fr” KHz” 


If you follow these guide lines, you reduce the chance of a 
calculation being a million, or even a billion, per cent out. 


Quadratic equations 


Over the years students have wrestled with the infamous ‘quad- 
ratic’, so most readers will be familiar with the following standard 
solution for the two answers (roots): 


If ax?+bx+c=0, then 


c= —b+V b?—4ac 
2a 


The presence of the square root in the equation implies that some 
values of the coefficients a, b and c can yield unreal solutions. It can 
be seen that the condition for unreal solutions is when 4ac is greater 
than b*. In fact the expression within the square root is known as 
the discriminant because, on evaluation, it ‘discriminates’ between 
real and unreal solutions. When writing equations which involve 
the solution of quadratics, it is wise to evaluate the discriminant part 
of the equation immediately because, if the result is negative, there 
is little point in proceeding further unless, for some reason, unreal 
values are considered ineresting. Subroutine 4.1 shows how to 
reject suspect coefficients before attempting solutions. 


Subroutine 4.1 Quadratic roots 


10 REM QUADRATIC ROOTS 


20 INPUT"Enter coefficient a ";a 
30 INPUT"Enter coefficient b "5b 





Subroutine 4.1 Quadratic roots 


40 INPUT"Enter coefficient c "3c 
50 GOSUB 10000 

60 END 

70 ° 

80 ° 

9999 REM FIND REAL QUADRATIC ROOTS 


10000 discrim=b*2—-4#a#c:r=—b/ (2#a) 

10010 IF discrim<O THEN PRINT"This gives unreal ro 
ots":GOTO 10040 

10020 u=SQR (discrim) / (2*a) 

10030 PRINT"X1="r+us PRINT" X2="r—u 

10040 RETURN 





Objective: To print out the two real solutions of a quadratic but reject 
unreal solutions. 

Variable names: 

a=coefficient of the squared x term. 

b=coefficient of the x term 

c=the constant term. 

discrim=variable holding the discriminant result. 

u=variable holding part of result. 

r=variable holding part of result. 

X1=one solution. 

X2=other solution. 

Action required before calling with GOSUB: Assign values to the three 
coefficients. 

Action required after RETURN: None. 

How it works: The discriminant is first evaluated and, if negative, a 
rejection message is displayed. 

Example calling program: Obtain the three coefficients from the 
keyboard. 

Suggested uses: Any program requiring a quadratic solution. 


Some readers, particularly those who have a background in elec- 
tronics, will be worried by complete rejection of unreal roots. They 
would argue that although they carry the label ‘unreal’ they occupy 
an important position in the theory of alternating currents in general 
and the behaviour of oscillatory circuits in particular. Unreal solu- 
tions can be rescued from the phantom world with the aid of the 90 
degrees operator j. (Operator i in pure mathematics.) It allows the 
two unreal solutions of a quadratic to be expressed in the form: 
R+jX and R—jx. Solutions which contain a combination of real and 
unreal terms are called complex solutions. The trouble is, how can 
we trick the computer into accepting complex solutions? The answer 
is to test the discriminant as before but, instead of rejection, convert 
it by means of the command ABS to the absolute value. In other 
words, change it to positive which is equivalent to reversing the terms 
within the discriminant. The equation needs to be slightly re-arranged 
so that the real and unreal terms are separated: 
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a = : V discriminant 

Séinond ae ay, tseemiinant 
2a 2a 

i —b : discriminant 

1 =p _, V_ailscriminant 
Solution 2 ae. _ 


The character j is merely a string character which should appear in 
the final printout of the solutions but can take no part in the 
calculations. It is an artifice for the benefit of humans as illustrated 
in Subroutine 4.2 


Subroutine 4.2 Complex quadratic solutions 


10 REM HANDLING UNREAL SOLUTIONS 
20 INPUT"Enter coefficient a "3a 
30 INPUT"Enter coefficient b "sb 
40 INPUT"Enter coefficient c "5c 
50 GOSUB 10000 

70 END 

80 ‘ 


90 ' 

9999 REM COMPLEX QUADRATIC SOLUTIONS 

10000 discrim=b*2—4*a*c:r=—b/ (2%a) 

10010 u=SOR(ABS (discrim) )/ (2a) 

10020 IF discrim<O THEN PRINT"X1="r"+ j"usPRINT"X2 
="e"— 3"u ELSE PRINT"X1="r+u:PRINT"X2="r—-u 

10030 RETURN 





Objective: To find both solutions, whether real or unreal. Unreal 
solutions are presented in operator j form. 
Variable names: 
a=coefficient of squared x term 
b=coefficient of x tem 
c=constant 
discrim=variable holding the discriminant of the equation 
r=real part of a complex solution 
u=unreal part of solution (if indeed the solution is complex). 
Action required before calling with GOSUB: Assign values to a, b and c. 
Action required after RETURN: None. 
How it works: Line 10000: the discriminant is evaluated. The real part 
is evaluated into r. Line 10010: The absolute value of the square root 
of the discriminant is evaluated into u, taking into account the 
denominator terms. Line 10020: tests the discriminant and prints 
out the two solutions. If the solutions are complex, the character ‘j’ 
is printed before the unreal component. 
Example calling program: This supplies the three coefficients from the 
keyboard. 

Suggested uses: only the real solutions can be used directly in 
other programs. The unreal solutions require special treatment. 


Subroutine 4.2 Complex quadratic solutions 


Rectangular/Polar conversion 


The position of a point in two-dimensional space can be expressed 
in terms of polar coordinates or cartesian coordinates. Instructions to 
travel 10 miles on a bearing of 45 degrees are in terms of polar 
coordinates. Instructions to walk along a certain street for 100 yards, 
then take the first street on the right and walk a further 50 yards are 
given in terms of cartesian coordinates. 

Polar coordinates measure the distance of a line from a fixed 
reference point and the angle of the line to a fixed reference line. The 
distance (length of the line) is called the modulus and the angle is 
called the argument. Polar form coordinates can be expressed in the 
form Z (the modulus) and 6 (the argument). 

Rectangular coordinates define a point in terms of its X and Y 
coordinates. Figure 4.1 shows both forms. 





Polar coordinates 
Z 


Reference line 


Rectangular 
coordinates : X=5 
Y=4 





Fig 4.1 
Converting cartesian to polar 
Z=VX*-+Y?: 8=ATN(Y/X) 


Example: If X=3 and Y=4, then Z=5 and 8=53.13 degrees. 
Equivalent programmed functions: 
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100 DEF FNmodulus(X,Y)=SQR(X*X+Y*Y) 
110 DEF FNangle(X, Y)=ATN(Y/X) 


To use the functions: 


200 Z=FNmodulus(X, Y) 
210 theta=FNangle(X, Y) 


To convert from polar to cartesian: 
X=Z*COS(angle):Y=Z*SIN(angle) 

Example: If Z=5 and angle=53.15 degrees, then X=5 cos 53.13=3 
and Y=5 sin 53.13=4 

Equivalent programmed functions: 


100 DEF FNxcoord(Z,angle)=Z* COS(angle) 
110 DEF FNycoord(Z,angle)=Z*SIN(angle) 


To use the functions: 


200 X=FNxcoord(Z, theta) 
210 Y=FNycoord(Z, theta) 


Statistics 


Mathematics is a highly respected discipline because various laws 
and formulae have survived the onslaught of rigid proof. The study 
of statistics occupies a somewhat dubious place in the field of 
mathematics, coming into prominence only when all else fails. If we 
can count, measure or calculate something, then we do it. If we 
can’t, either because it is impractical or because of ignorance of the 
underlying mechanisms, then we fall back on statistics. It is the last 
resort when all else fails. Statistics supplies us with figures derived 
from well-proven probability laws, but leaves us to interpret them in 
a common-sense manner. It is incorrect interpretation, often quite 
deliberate, which tends to slur the image of statistics and renders 
them a boon to politicians and advertisers. 

If you present a statistician with a sample of seemingly random 
figures, he/she will often come up with some predictions but they 
will be issued with caution. For example, the sample may be too 
small for reliable predictions to be made. Statistics is all to do with 
samples. The larger the sample, the higher the confidence factor 
that the sample results can be extended to the total population. (The 
term population refers to the total number of items, not necessarily 


people.) 


Collecting the data 
Data, as far as statistics is concerned, is a set of numbers. What the 
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numbers stand for is not always of importance to statistics. The set 
of numbers could be shoe sizes or the distance between the navel 
and armpit of a sample of people. The collection of data is normally 
a field exercise, the end result being sheets of paper. The figures on 
the paper will be entered into a computer and one or more statistical 
formula brought to bear on them. Subroutine 4.3 will allow a 
number of figures to be entered and will find the mean value and the 
standard deviation. The mean is easy. Just add up the numbers and 
divide by the number of numbers on the list. The standard deviation 
is another matter and demands more explanation than we have 
space for. The formula is usually expressed in the following form: 


Y_X)2 
Standard deviation= px 


where X=value of item 

X=mean value of X terms 

N=number of items 

2 means the ‘algebraic summation of’ 
We include it because, of all the statistical operations available, it is 
the most useful and probably the best known. 


Subroutine 4.3 Find mean and standard deviation 


10 REM EXAMPLE: FIND MEAN & STANDARD 
20 REM DEVIATION OF A LIST (ARRAY) 
30 CLS 

40 INPUT"How many numbers in list";numZ 
SO DIM L(num7Z) 

60 FOR NZ=1 TO numZ 

70 PRINT"Enter number" 

80 INPUT L(NZ) 

90 NEXT 

100 INPUT"decimal places reqd";P% 
110 sizeZ=numZ: places%Z=P% 

120 GOSUB 10000 

130 m=mean: s=dev 

140 PRINT"The mean of the list is"3m 
150 PRINT"The standard deviation is";s 
160 END 

170 ° 

180 ' 

9998 REM MEAN & STANDARD DEVIATION 
9999 REM SUBROUTINE 

10000 sum=0 

10010 FOR NZ=1 TO sizez% 
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sum=sum+L (NZ) 
NEXT 
mean=sum/sizeZ 
subtotal=0 

FOR NZ=1 TO sizez% 


subtotal =subtotal + (L (NZ) —mean) “2 
NEXT 

dev=SQR (subtotal /sizeZ) 
mean=ROUND (mean ,pl aces) 
dev=ROUND (dev ,places~) 

RETURN 





Objective: To find the mean and standard deviation of a set of 
numerical items in an array. 

Variable names: 

sum=arithmetical sum of all items 

L(N%)=an individual number in the array 

size% =number of items currently in the array 

mean=arithmetic mean of all numbers 

subtotal=an intermediate stage in calculation of standard deviation 
dev=standard deviation 

places% =number of decimal places required 

num% =maximum number of items in array. 

Action required before calling with GOSUB: Items must be in L(N%). 
Action required after RETURN: Assign mean and dev to variables of 
your choice. 

How it works: The first FOR/NEXT loop finds sum of all items. The 
mean is then found. The second FOR/NEXT loop calculates the total 
of all separate squares of each (item minus the mean) value. The 
standard deviation is then calculated and finally rounded. 

Example calling program: Places all numbers entered from keyboard 
into the array, L, and obtains values for number of decimal places 
before calling on the subroutine. On return, the mean and standard 
deviation values are re-assigned to variables m and s before being 
displayed on the screen. 

Suggested uses: for incorporation into general statistical programs. 


Factorials 

The factorial of integer X, written X!, is the product of all integers from 
1 to X. For example, 4!=4x3x2x1=24. Factorials have a nasty habit of 
growing to astronomical proportions with even moderate values of 
X. Even 10! evaluates to 3,628,800, so one problem to watch out for 
is overflow. The overflow limit is nearly reached with 30! because it 
has an approximate value, 2.6E32. A strange feature of factorials, 
representing another possible hazard, is that 0! and 1! both=1. 
Factorials feature prominently in the laws of probability and 
combinations. 


Subroutine 4.3 Find mean and standard deviation 


Subroutine 4.4 Calculate factorial 


10 REM EXAMPLE: FIND FACTORIAL 

20 CLS 

30 INPUT"Enter number (1 to 20)"53NZ 

40 numberZ=N%Z:GOSUB 10000 

50 PRINT"The factorial of "NZ" is "fact 
60 END 

7O ° 


9999 REM CALCULATE FACTORIAL 
10000 fact=1 

10010 IF number%Z=0 THEN 10050 
10020 FOR L%=number% TO 1 STEP -1 
10030 fact=fact#LZ% 

10040 NEXT 

10050 RETURN 


Objective: To take a number and calculate the factorial equivalent. 
Variable names: 

number% =variable holding the number 

fact=variable holding the factorial of number% 

L%=loop counter. 

Action required before calling with GOSUB: Assign the number to 
number%. 

Action required after RETURN: Re-assign fact to the variable of your 
choice. 

How it works: The loop uses a negative step so all successive integers 
below number% are progressively multiplied. 

Example calling program: Obtains the number in N% and re-assigns it 
to number% before calling the subroutine. There is no built-in 
protection for overflow if N% is too large. 

Suggested uses: There are many equations in statistics and probability 
which employ factorials. 


Hash tables 


Imagine an array containing items in random order, and we want to 
check quickly for the inclusion of a particular item within that array. 
We would normally think in terms of a sequential search through the 
array until the item was either found, or deemed not to exist. If, in 
some application, this was to be performed many times the execu- 
tion time may well be unacceptable, particularly so if the array was 
large. 

Frenne there is a solution in the form of a hash table. This 
techniques takes full advantage of the random access nature of 
elements within an array. Instead of storing items sequentially in an 
array, the question which immediately comes to mind is ‘Why not 
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calculate an array address based on the actual item itself?’ Alas, 
there are problems. Items stored in arrays may be expressed as a 
combination of letters, combination of numbers or a mixture of 
both, for example, the results of a scientific experiment or the name 
of a stamp in a collection. Unfortunately, the nature of direct access 
is alien to the concept of retrieval based on the actual item itself. 
Elements of random access arrays are accessed by an array index. For 
example position N% in an array A% would be accessed as 
A%(N%). This means that space in the array must be available for 
as many items as there are possible combinations of the key field 
characters — even if most of them will never be used! 

This is a formidable restriction. To see why, let us consider a 
string array consisting of a list of stamps in a particular collection. 
For simplicity, restrict the number of possible letters in the name to 
10. There are 26 letters in the alphabet so there are 26'° different 
ways of arranging the letters, which is approximately 10". 
Obviously, an array that size could not be DIMensioned. Morever, 
many of the possible combinations would not occur in practice. For 
example, a penny ‘zxpler’ or blue ‘dhegfart’ would be unlikely. 

However, even if we are quite ruthless and say that out of the 10" 
theoretical combinations there are only 10° practical ones, it is still a 
large number — 100 million in fact. And yet, a large array in a 
microcomputer is unlikely to be DIMensioned to more than 2 or 3 
thousand elements. We could say, therefore, that the list of possible 
combinations is only sparsely populated with real ones. This leads to 
the conclusion that direct access to a particular array address, by 
supplying the search key, may certainly be faster than a sequential 
search, but the storage space required would stretch the capacity of 
even a mainframe giant. 

In summary, we must conclude that it is rarely possible in practice 
to achieve a one to one fuctional transformation of a search key to an 
array address. The search key must be mapped to one of the range 
of elements DIMensioned in the array. 


Hash functions 
It is possible to retain the speed of direct access to a particular array 
element without seriously jeopardising storage capacity by the use 
of a hash function. 

In the following summary, we shall assume that a hundred six- 
digit numbers are to be stored in an array: 


1 The array size is DIMensioned at 100. 

2 The six digit numbers to be stored in each array element are then 
used as input to a suitable ‘hash’ function. 

3 The output from the hash function is a transformation of the 
number and points directly to a particular array location. 


For example, suppose we DIMensioned an array A%(100) and the 
number to be stored was a 6 digit number. The number, calculated 
by the hash function, would always be within the range 0 to 100. 


Hash tables 


The enormous number of possible keyfield combinations is thus 
scaled down by the hash function to just the number required for the 
DIMensioned array. We now have the best of both worlds. The 
number itself can be used to access the location where it should be 
stored. Thus an array search can be performed immediately without 
wasting large areas of memory. 

Is this too good to be true? Well, it is almost true but, as might be 
expected, there are problems to overcome. Whatever hash function 
is chosen, there is no 100% guarantee that a calculated array address 
will be unique. There is a probability that, occasionally, two items 
will bear the same calculated array address. When this happens, the 
two items are said to collide. On the face of it, collisions would 
appear to have catastrophic effects on the behaviour patterns of 
direct access. Fortunately for the reputation of hash coding, careful 
programming can allow for collisions quite easily. 

Before treating collisions in detail, we must examine some actual 
hash functions. 

A hash function takes a number and scrambles it. The more the 
number is mixed up (randomised), the better. In short, it makes a 
hash of the number, hence its name. The random number generator 
in a computer works in a similar manner. Apart from mixing up the 
number, the primary aim is to reduce a multi digit number to one 
containing fewer digits. Another requirement is to ensure, as far as 
possible, that the resultant number is different each time the hash 
function operates. However, it is important that the output from the 
hash function is reproducable. That is to say, the output is consist- 
ant with a particular input. The hash function most suited to small 
microcomputers is perhaps the division remainder method. 


Division remainder hashing 


This function is based on modulo arithmetic. The number N% to be 
stored is divided by another number, size% (usually that at which 
the array is DIMensioned) and the remainder taken as the hash 
result. In BASIC notation, N% MOD size% performs this function. 
Example: If N=3456 and the array size, size%, is 97. Dividing 3456 
by 50 yields the whole number 35 leaving a remainder of 61 which is 
the hash code. We are fortunate that Amstrad BASIC can calculate 
modulo functions directly. A better spread of numbers usually 
results if a prime number is used as the divisor. In a practical 
situation, the prime number should be the highest prime, consistent 
with being lower than the maximum number of array elements 
dimensioned. Subroutine 4.5 uses the division remainder method to 
calculate its output. Many other hashing functions are possible but 
it is pointless describing any more. The only requirement of a hash 
function is that it should produce well spread random numbers 
within a specified range and should execute rapidly. In fact, the 
particular hash function used is not all that important, as long as the 
number is well scrambled. 
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Subroutine 4.5 Number hashing subroutine 


10 REM EXAMPLE: HASHING NUMBERS 

20 CLS 

30 WHILE 1<>2 

40 INPUT"Enter any number";K 

50 number=K: sizeZ=100 

60 GOSUB 10000 

70 PRINT"The hash code generated is"hash% 


80 WEND 
90° 


9999 REM NUMBER HASHING SUBROUTINE 
10000 WHILE number >32767 

10010 number=number /2 

10020 WEND 

10030 hashZ=INT (number) MOD sizez% 
10040 RETURN 





Objective: To generate a hash code within a certain range from any 
positive number, irrespective of its size. 


Variable names: 

number=the actual number to be hash coded 

size% =the upper limit of the range of permissible hash codes. The 
lower limit is always zero 

hash% =the generated hash code between the limits 0 to size% 


Action required before calling with GOSUB: Assign the number to be 
hash coded to the variable number. Assign the upper limit of 
permissible hash codes to the variable size%. 


Action required after RETURN: Assign the variable of your choice to 
hash% 


How it works: The number input to the hash function is progressively 
halved until it is within the range of integer arithmetic handling on 
the Amstrad machine (0 to 32767). This process is performed by the 
WHILE/WEND loop lines 10000 to 10020. The hash code itself is 
generated in line 10030 by use of the MOD operation. The re- 
mainder from integer division of number by size% is taken as the 
hash code and assigned to hash%. 


Example calling program: The number to be hashed is input into the 
variable, K, and later assigned to number in line 50. The calling 
variable, size%, is set arbitrarily to 100. The subroutine is called in 
line 60 and the resultant hash code, within the range 0 to 100, is 
displayed by line 70. Press escape twice to exit the test example 
program. 

Suggested uses: To map numbers of any size to a particular array 
location. However, collision resolution techniques such as linear 
probing must be used to resolve occasional location clashes. 


Subroutine 4.5 Number hashing subroutine 


Hashing strings 


If alphabetical characters are used as key fields in a file the same 
techniques apply. All that is necessary is to convert the string to a 
number in some reproducable way. For instance, convert letters to 
their ASCII codes prior to choosing a hash function. The codes can 
be mixed, chopped, added in a variety of different ways. As an 
example Subroutine 4.6 shows how to perform this in a quick and 
easy way. 


Subroutine 4.6 String hashing subroutine 


10 REM EXAMPLE: HASHING STRINGS 

20 CLS 

30 WHILE K#<>"end" 

40 INPUT"Enter string";K? 

50 hash$=K$#: sizeZ=100 

60 GOSUB 10000 

70 PRINT"The hash code generated is"hashZ% 
80 WEND 

90 END 

100 ° 

9999 REM STRING HASHING SUBROUTINE 
10000 A=ASC (hash$) 

10010 B=ASC (RIGHTS (hash$,1)) 

10020 hashZ=A+B#LEN (hash) 

10030 hashZ=hashZ MOD sizeZz 

10040 RETURN 


Objective: To generate a hash code within a certain range from any 
string, irrespective of its length and content. 

Variable names: 

hash$=the actual string to be hash coded 

A=The ASCII code of the first character of hash$ 

B=The ASCII code of the last character of hash$ 

size% =the upper limit of the range of permissible hash codes. The 
lower limit is always zero. 

Action required before calling with GOSUB: Assign the string to be hash 
coded to the string variable, hash$. Assign the upper limit of 
permissible hash codes to the variable size%. 

Action required after RETURN: Assign the variable of your choice to 
hash%. 

How it works: Line 10000 sets the variable A to the ASCII value of the 
first character in the string. The line is completely equivalent to 
A=ASC(LEFT$(hash$,1)) since the ASC command directly returns 
the ASCII code of the first character in hash$. Line 10010 sets the 
variable B to the ASCII code of the last character of hash$. 
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Line 10020 multiplies B by the length of hash$ and adds it to A. This 
produces a fairly large number based on hash$ which is finally 
hashed by the division remainder method in line 10030. 

Example calling program: The string to be hashed is input into the 
variable, K$, and later assigned to hash$ in line 50. The calling 
variable size% is set arbitrarily to 100. The subroutine is called in 
line 60 and the resultant hash code within the range 0 to 100 is 
displayed by line 70. Enter ‘end’ to exit the test example. This is 
controlled by the WHILE/WEND loop. 

Suggested uses: To map strings of any composition or length to a 
particular array location. However, collision resolution techniques 
such as linear probing must be used to resolve occasional location 
clashes. 


Handling collisions 


Whatever hash coding techniques are used, some collisions will 
undoubtedly occur when storing array elements. The probability of 
collision is low at first because there are plenty of unoccupied 
locations, but as the array begins to fill up with items, the 
probability increases. There are several programming techniques 
for handling a collision, using so-called open addressing techniques. 


Linear probing 

This method tests the array address to which the item is directed 
through the hash function to see if it is already occupied. If it is, 
then the next adjacent location is tried. If this is occupied, the next is 
tried, and so on, until an unoccupied location is found. Trials all 
take place in the same direction. If, by chance, the last location in 
the array has been tested without success, the first one in the array 
is tried (wrap around). On returning to the original transformed 
location, it will be evident that the array is full. In practice, this 
situation is unlikely because over-allocation of array space by about 
40% should be used to avoid frequent collisions. 

If an item is to be retrieved, the search key is compared with the 
item stored in its transformed location. If the array location is not 
occupied by the desired key then a sequential search is made in the 
same direction (wrap around) until the record is either found or 
deemed not to exist. The latter decision can be made as soon as an 
unused array location is found. Subroutine 4.7 is a practical example 
of the use of linear probing. 


Clustering 

One of the major disadvantages of linear probing is that when the 
array becomes 50% to 60% full, the increased collision rate leads to 
clustering. Clustering is a technical term used to describe the 
tendency of many stored items to appear in adjacent array locations. 


Handling collisions 


This can lead to longer and longer sequential searches being 
necessary to cope with collisions as the array is filled. Over allocation 
of array space is the solution to clustering. 


Rehashing 

A solution to the problem of collision resolution, while at the same 
reducing the tendency of clustering, is rehashing. A second hash 
function is used to find an alternative record slot for the colliding 
items. If this location is also filled it will be necessary to rehash 
again. 


Subroutine 4.7 Linear probing of a hash table 









REM EXAMPLE: REJECTING DUPLICATE 
20 REM DATA USING A HASH TABLE 
30 CLS 

40 PRINT"Example 1:" 

SO READ items” 

60 sizeZ=itemsZt+itemsZ/2 

70 DIM A#(sizeZ) 

80 FOR N=1 TO items~% 

90 READ words 

100 try#=word$:GOSUB 10000 

110 IF flag%=0 THEN A$ (probe) =try$: count%Z=count%~+ 
1:PRINT try$¢ 

120 NEXT 

130 PRINT"Number in list ="items% 

140 PRINT"Number stored in table ="count% 

150 PRINT"Number of duplicates ="items%Z-count% 

140 ’ 



















170 ‘---------------------------------- 
180 ' 

190 REM EXAMPLE : CHECKING FOR AN ITEMS 
200 REM INCLUSION IN A HASH TABLE 






210 PRINT: PRINT 

220 PRINT"Example 2:" 

230 PRINT"Enter item to check with table" 

240 INPUT K¢ 

250 KS=UPPERS (K#) 

260 IF K$=""" THEN K$="0" 

270 try#=K$:GOSUB 10000 

280 IF flag%=1 THEN PRINT"Item found at table posi 
tion"probe% ELSE PRINT"Item not in table" 

290 END 

300 ° 

310 DATA 28 

320 DATA PIG,DOG,PIG,CAT,PIG,DOG,CAT,CRAB,LOBSTER, 
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PIG,CAT,DOG, ELEPHANT ,CAT, PIG, DOG,LOBSTER, ELEPHANT , 
CRAB ,CAT ,DOG,PIG,CAT,DOG,LOBSTER, SHRIMP ,CAT ,DOG 
330 ° 

340 ° 

9999 REM LINEAR PROBING SUBROUTINE 

10000 flag%=-1 

10010 hash$=try$ 

10020 GOSUB 11000: probe%=hashz 

10030 WHILE flag%=-1 

10040 IF try$=A¢$(probeZ) THEN flag%Z=1:GOTO 10060 
10050 IF A#(probeZ%)="""THEN flag%Z=0 ELSE probe%~=(p 
robeZ+1) MOD sizeZ% 

10060 WEND 

10070 RETURN 

10080 ‘ 

10999 REM STRING HASH FUNCTION 

11000 A=ASC (hash$) 

11010 B=ASC (RIGHTS (hash$, 1) ) 

11020 hash%Z=A+B*LEN (hash$) 

11030 hashZ=hash% MOD sizeZ 

11040 RETURN 





Objective: To resolve collisions in a hash table by linear probing. 
Variable names: 

flag%=status variable to be examined by calling program. The 
variable flag%=1 when table address is occupied by a duplicate 
item and flag%=0 when a blank table address is found. It is left at 
—1 if a collision has occurred. 

try$=the string element to be checked or stored at the address 
calculated by the hash function. 

probe% =probe% is the current table (array) address that is cur- 
rently being probed. 

size% =is hash table size used in the DIMension command. 

hash% =is the variable returned by the hash function. 

hash$=is the variable assigned to try$ prior to a call to the hash 
function subroutine. 

Action required before calling with GOSUB: The variable try$ must be 
set to the string that is to be compared in the hash table. 

Action required after return: The variable flag% is examined by the 
calling program and various actions can be performed, as appro- 
priate, on the table location indexed by probe%. That is to say, 
AS(probe%). 

Dependent subroutines or functions: Must be used in conjunction with 
the string hash function subroutine at line 11000. 

How it works: The subroutine is called with try$ set to the string to be 
checked in the hash table. The variable flag% is initialised to —1 in 
line 10000. The string hash function subroutine is called in line 10020 
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after first copying try$ into hash$. On return, probe% is set to the 
hash coded result. Three tests are made inside the WHILE/WEND 
loop. Firstly, the variable flag% is set to 1 if try$ is equal to the 
contents of the array indexed by probe%. If this is so the loop is 
terminated. Secondly, if the indexed array position is empty (null 
string) then flag% is set to zero and the loop terminated. This 
indicates the array position is available for an insertion. If neither of 
the above tests are true, a collision has occurred. Linear probing is 
used to resolve it and execution proceeds to the ELSE command in 
line 10050. This increments probe% by one (wrap around) and 
leaves flag% set at —1. The tests are then repeated at the next 
probe% array position. 

Example calling program: There are really two test programs with this 
subroutine. The first shows how to use the subroutine for storing 
data in a hash table and the second how to use the subroutine for 
direct access to a stored item. 

Example program 1: Rejecting duplicate data with a hash table. 

Line 50 reads the number of DATA items placed in line 310. 
Line 60 increases this number by 50% and DIMensions the table 
(array) in line 70. Note that extra elements are needed to reduce the 
likelihood of collisions. The data items, in this case simply a list of 
common pet animals, are read in and stored only if they are unique. 
The linear probing subroutine is called in line 100 after each data 
read. The data item is compared against that already stored at the 
probed hash table position. If on return, flag% is set to zero, this 
indicates the data has not previously been stored so the data is 
displayed. A count of unique animals is updated and stored in 
count%. Finally, various information including the number of 
duplicates etc are displayed. 

Example 2: Checking for an item’s inclusion in a hash table. 

This example is used to find the table position of a hash coded 
string. The array index will be left in the variable probe%. The only 
difference with this example is in the way flag% is interpreted. If 
flag% is set to zero on return from the linear probing subroutine, 
then the item is deemed not to be present in the table. Remember 
that a search by linear probing can be abandoned as soon as a vacant 
array position is encountered. On the other hand, if flag%=1 then 
the string is found at position probe%, (A$(probe%)). 

Suggested uses: Any application that needs to reject or count dupli- 
cate data, store and retrieve data to/from an array many times. Can 
even be used in a data base type program for ultra-fast storage and 
retrieval of records by keyfield. 

Notes: Linear probing works equally well for numeric or string 
arrays. For numeric, simply substitute floating point or integer 
variables for the key string ones above. 


Combinations 


Combinations refer to the number of different ways we can select k 


77 


78 





Mathematical subroutines 


items from a total of n items without regard to order. For example, if 
we have the letters ABCDEFGH, how many different ways can we 
select any five of them? The answer is obviously quite a lot. A 
computer can help by not only finding out how many ways there are 
but, if required, can display the actual arrangements as well. The 
following is a formula for finding the number of combinations: 


N! 
(N-k)! K! 
where C=number of combinations of K items selected from a total 
of N items. 
Unless precautions are taken, the task of finding and printing out 
all combinations can take quite a time, even on a computer. Program 


4.1 finds the number of combinations, given N and K, sorts the 
combinations in order and displays them. 


C= 


Program 4.1 Finding combinations using a hash table 


10 REM PROGRAM:FINDING COMBINATIONS 

20 REM USING A HASH TABLE 

30 MODE 1 

40 CLS 

SO INPUT"Enter items selected each time";k% 
60 INPUT"Enter total number of items "5;n% 
7O IF k%Z>nZ% OR kZ<1 OR nZ%Z<1 OR nZ>26 THEN PRINT"In 
put invalid":GOTO 50 

80 mZ=nN4-kZ 

90 number%Z=nZ:GOSUB 340: a=fact 

100 number%=k%Z:GOSUB 340:b=fact 

110 numberZ=mZ: GOSUB 340:c=fact 

120 C%=a/ (b*¥c) 

130 choice$="" 

140 FOR L%Z=1 TO n% 

150 D#=CHR$ (64+L%) 

160 choice$=choice$+D$ 

170 NEXT 

180 countZ=0:GOSUB 4680 

190 size%Z=CZ#2 

200 DIM A#(sizeZ) ,BS(CZ) 

210 WHILE countZ<CZ% 

220 try#=choice$:GOSUB 420 

230 GOSUB 500 

240 LOCATE 1,5 

250 PRINT"Combinations found =" 

260 IF flag%Z=0 THEN A¥# (probe) =try$: countZ=count%+ 
1: B% (count%) =try$:LOCATE 22,5:PRINT countZ% 
270 WEND 


450 
) 

440 
470 
480 
490 
500 
510 
520 
530 
540 
550 
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PRINT"Sorting data into order: Please wait" 
GOSUB 840 

GOSUB 470 

END 


REM CALCULATE FACTORIAL 
fact=1 

IF number%Z=0 THEN 390 

FOR L%=number% TO 1 STEP -1 
fact=fact#L7% 

NEXT 

RETURN 


REM GET NEXT TRIAL STRING 

IF n%=k% THEN 470 

FOR L%=1 TO m% 

TZ%=INT (RND#LEN (try$) ) +1 

try$=LEFT$ (try$,1T%—-1) +RIGHTS (try$,LEN (try) -T% 


NEXT 
RETURN 


REM LINEAR PROBING SUBROUTINE 

flag%Z=-1 

hash$=try$ 

GOSUB 400: probeZ%~=hash% 

WHILE flag%=-1 

IF try$=A$(probe%) THEN flag%=1:GOTO 560 

IF A$(probeZ)=""" THEN flag%=0 ELSE probe%=(pro 


be%Z+1) MOD sizez 


560 
570 
580 
590 
400 
610 
620 


WEND 

RETURN 

REM HASH FUNCTION SUBROUTINE 

hashZ=0 

FOR L%=2 TO k% 
hashZ=hashZ+ASC (MID$ (hash$,LZ%,1)) #ASC (MIDS (has 


h$,L%-1,1)) 


630 
640 
650 
660 
670 
680 
690 
700 
710 





hashZ=hashZ MOD sizeZ% 

NEXT 

RETURN 

REM DISPLAY COMBINATIONS 
CLS:PRINT"Choices from ";choice$ 
PRINT"Combinations ("kZ" from "nZ") ="sC% 
PRINT 

IF count%Z=0 THEN 810 
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720 FOR itemZ=1 TO count% 

730 IF item%Z MOD 20=0 THEN GOSUB 940 
740 PRINT itemZ":"TAB(13) BS (itemZ) 
750 NEXT 

760 PRINT: PRINT"Repeat display (Y/N)" 
770 K$="" WHILE K$<>"Y" AND K$<>"N" 
780 KS=UPPERS$ (INKEY$) 

790 WEND 

800 IF K#="Y" THEN 680 

810 RETURN 

820 ‘ 

830 REM SELECTION SORT 

840 FOR I%=count% TO 2 STEP -1 

850 MZ=1 

860 FOR J%Z=2 TO 1% 

870 IF BY(J%)>BS(MZ) THEN MZ=J% 

880 NEXT 

890 T$=BS (MZ) : BS (MZ) =BS (1%) BS (1%) =TS 
900 NEXT 

910 RETURN 

920 ' 

930 REM HOLD DISPLAY 

940 PRINT:PRINT"Press any key to continue display" 
:PRINT:K$=""]WHILE K$="":K$=INKEY$: WEND 
950 RETURN 





Using the program 

The first prompt is ‘Enter items selected each time’ and is followed 
by ‘Enter total number of items’. For example, if you want the 
combinations resulting from the selection of any 3 out of 6, you 
would enter 3 in response to the first prompt and 6 to the second. 
While the computer is finding the various combinations a running 
total of the number found is displayed on the screen. When all have 
been found the message ‘Sorting data into order: Please wait’ is 
displayed. The screen then clears and displays the actual combina- 
tions in sorted batches of twenty on pressing the SPACE bar. The 
‘items’ are represented on the computer by upper case letters of the 
alphabet but they must be interpreted as symbolic representations 
of any group of objects. For example, ABCDE could represent five 
different objects ranging from various coloured balls to the number 
of stripes on a zebra. 

The program may take a little time, hence the message ‘— Please 
wait’. We should remember that the poor computer has quite a lot of 
work to do. It must find every combination and finally sort the 
combinations into alphabetical order. 


How Program 4.1 works 
In lines 50 and 60 the number of items to be selected each time is 
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entered into the variable k%. The total number of items to select 
from is input into n%. 

Line 70 performs various input validation. Line 80 sets m% to the 
difference between selected number and total number. 

Lines 90 to 110 call the calculate factorial subroutine at line 340 
three times. The factorials of n%, k% and m% are assigned to a, b 
and c respectively. 

Line 140 performs the actual calculation on the number of 
combinations and stores the result in C%. 

Lines 130 to 170 are a FOR/NEXT loop which sets up a string, 
choice$ of length n% characters. The characters are in alphabetical 
order. That is to say, choice$=“ABCDEFG” if n%=7. This is the 
string that combinations will be chosen from. 

Line 180 initialises count%, the number of combinations found. 
A call to display combinations displays the number of combinations 
k% from n%. 

Line 190 calculates the size of the hash table or array. This is 
chosen as twice the possible number of combinations so that 
collisions will be few. 

Line 200 DIMensions the hash table, A$, as well as a further array, 
B$, for conveniently copying unduplicated combinations. 

Lines 210 to 270 form a WHILE/WEND loop which, randomly, 
extracts m% =n% —k% characters from choice via a call to ‘get next 
trial string subroutine’ at line 420. Each trial, try$, is tested for 
uniqueness by using hashing and linear probing of the type dis- 
cussed earlier in Subroutine 4.7. Line 260 interrogates the variable 
flag% and, if zero, stores try$ both in the hash table array and the 
valid combination array, B$. As the actual combinations are found a 
‘Combinations found’ display is updated. The loop is terminated 
when all the possible combinations have been found. This occurs 
when count%=C%. 

Lines 290 to 300 are calls to sorting and display subroutines. The 
valid combinations are stored and sorted in the array, B$. 


Calculate factorial (GOSUB 340) 
This subroutine is identical to Subroutine 4.4 


Get next trial string (GOSUB 420) 

The subroutine randomly extracts m%=n%—k% characters from 
choice$ and leaves the remaining characters in try$. A loop is 
executed where one character at a time is removed m% times. In 
this way, the original order of the string characters is preserved. 
Imagine, for a moment, the problem of checking whether BFAC is 
the same combination as FACB! This alleviates the need for a fairly 
lengthy string comparison algorithm during linear probing. 


Linear probing subroutine (GOSUB 500) 
The subroutine is identical to Subroutine 4.7. 
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Hash function subroutine (GOSUB 600) 

The subroutine is a modified version of Subroutine 4.5. Changes are 
needed because all the strings that are input into hash are all the 
same length rendering Subroutine 4.5 useless. The problem is 
overcome by multiplying and adding the ASCII codes of adjacent 
pairs of characters throughout the length of the string. The hash 
code is finally calculated by the division remainder method. 


Display combinations (GOSUB 680) 

This is a fairly straightforward subroutine which displays the 
combinations stored in the array B$ in groups of twenty at a time. 
The MOD operator in conjunction with a ‘press any key to continue’ 
subroutine performs this function. The provision has been included 
to re-display the entire array in lines 760 to 800. 


Selection sort (GOSUB 840) 
This subroutine is similar to Subroutine 8.4 


Hold display (GOSUB 940) 
The subroutine is identical to Subroutine 3.1 


Solving polynomial equations 


Subroutine 4.1 obtained the roots of a quadratic equation, using a 
formula known since antiquity. A quadratic is classed as an equation 
of the second degree, meaning that the highest power of the 
variable X is 2. There is also an equation for solving an equation of 
the third degree (cubic). Both the quadratic and the cubic are two 
members of a class known as polynomial equations, having the 
general form: 

O=at+bx+cx?+dx?+ex*+fhOo+gx°+ .. . etc etc 

There are, in theory, n solutions of a polynomial of degree n 
although not all of them will necessarily be real. As far as we are 
aware, no solution for the fifth or higher degree has ever been 
found. So what do we do if, for some obscure reason, we want to 
solve an equation of the 13th degree? The answer is to fall back on 
trial and error methods. You guess a value for x, substitute it in the 
formula and see if the result is zero. If not, you try another value 
and then another until you eventually hit the target or perish from 
exhaustion — whichever comes first. 

It helps if you approach the task methodically, taking note of the 
way in which the trial solution is progressing. A trial and error 
process, each trial becoming a little closer to the correct solution, is 
called iteration. As the trials go on and the solution is seemingly in 
sight, it is important not to overshoot, causing the goal to recede in 
the opposite direction. For this reason, we do not insist on an 
accurate solution. Instead, the trials continue, using smaller and 
smaller increments of the trial variable until the solution is found 


Solving polynomial equations 83 


within a desired accuracy. Humans are not suited to iteration. They 
tire easily and, because they calculate slowly, would often grow old 
before finding a solution. In contrast, iterative processes hold no 
fears to a computer because millions of trial solutions could be 
achieved in minutes, perhaps seconds in some cases. Program 4.2 
should find all the real roots, if they exist, of a polynomial of any 
degree. The average time taken to find the roots depends on: 


1 the desired accuracy, 

2 the degree of the equation, 

3 the degree of common sense on the part of the operator 
supplying the initial trial guess. 


Program 4.2 Solving polynomials 


10 REM PROGRAM: SOLVING POLYNOMIALS 

20 MODE 1 

30 GOSUB 740:PRINT"SOLVE POLYNOMIALS (follow instr 

uctions":GOSUB 740 

40 PRINT"Current DEFined function is listed" 

50 PRINT:PRINT"Modify the program line as required 

60 PRINT"but only to the right hand side of =" 

70 PRINT:PRINT"When satisfied type the command RUN 
100 

80 GOSUB 760:PRINT 

90 LIST 100 

100 DEF FNpol ynomial (x) =X*3- (4#X*%2)+X+1 

110 DIM root (20) 

120 GOSUB 190 

130 GOSUB 320 

140 GOSUB 430 

150 LIST 100 

160 END 

170 ‘ 

180 REM GET INPUT 

190 CLS 

200 low=-1000: high=1000: type%Z=0 

210 PRINT"Enter first X limit" 

220 GOSUB 820: XminZ=K 

230 PRINT"Enter second X limit" 

240 GOSUB 820: XmaxZ=K 

250 IF XminZ>Xmax% THEN Xmax%=XminZs XminZ=K 

260 PRINT"Enter Accuracy required (min error)" 
270 low=1E-12:high=0. 1stypeZ=1 

280 GOSUB 820: accuracy=K 

290 RETURN 

300 ' 
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310 
320 
330 
340 
350 
360 


370 
380 
390 
400 
410 
420 
430 
440 
450 
460 
470 
480 
490 
500 
510 
520 
530 
540 
550 
560 
570 
580 
590 
600 
610 
620 
630 
640 
650 
660 
670 
680 
690 
700 
710 
720 
730 
740 
750 
760 





REM CALCULATE SOLUTIONS 

NZ=1: X=XminZ%: last X=X 

last Y=FNpol ynomial (X) 

FOR X=XminZ+1 TO Xmax% 

Y=FNpol ynomial (X) 

IF Y*¥lastY<O THEN Xlow=lastX: Xhigh=X:GOSUB 550 


:root (NZ) =sol : NZ=NZ+1 


IF Y=0O THEN root (NZ) =X: NZ=NZ+1 
lastX=X:lastY=Y 

NEXT 

RETURN 


REM DISPLAY SOLUTIONS 

CLS 

PRINT"Range of Xz "3XminZz" to "XmaxZ% 
PRINT"For F(x)=0 the real solutions are :" 
GOSUB 740 

FOR KZ=1 TO NZ-1 


PRINT"Solution ";K%" = "sroot (K%) 
GOSUB 740 

NEXT 

IF N%=1 THEN PRINT"None":GOSUB 760 
RETURN 

REM NON INTEGER SOLUTION ITERATION 


E=1 

WHILE E>accuracy 

XX=(Xlow+Xhigh) /2 

E=E/2 

YY=FNpol ynomi al (XX) 

IF YY>lastY THEN GOSUB 660 ELSE GOSUB 710 
WEND 

801 =XX 

RETURN 


REM POSITIVE SLOPE 

IF SGN(YY)=-1 THEN Xlow=XX 
IF SGN(YY)=1 THEN Xhigh=XX 
RETURN 

REM NEGATIVE SLOPE 

IF SGN(YY)=-1 THEN Xhigh=XX 
IF SGN(YY)=1 THEN Xlow=XX 
RETURN 


REM DRAW LINE 
PEN 3 





Program 4.2 Solving polynomials 


770 PRINT STRINGS (40, CHR (154) ) ; 
780 PEN 1 

790 RETURN 

800 ° 


810 REM NUMERICAL INPUT VALIDATION 


820 INPUT K 

830 IF typeZ=0 AND K<>INT(K) THEN PRINT"Input not 
an integer":GOTO 820 

840 IF K<low OR K>high THEN PRINT"Input out of ran 
ge":GOTO 820 

850 RETURN 





Using the program 

This is one of those programs where a little extra cooperation is 
required from the user. The equation to be solved is buried within a 
defined function (see line 100) but, to make the operation easier in 
the first instance, a sample equation already exists so you can 
practise using the rest of the program without worrying. It is a third 
degree equation and appears on the screen as follows: 


100 DEF FNpolynomial(x)=X*3—(4%X*2)+X+1 
If you want a different equation, the procedural steps are: 


1 Modify the program line, using normal editing keys, but ONLY 
that part to the right of the ‘=’ sign. 
2 After modification, type the command RUN 100. 


Screen prompts will then ask for trial limits: 
‘Enter first X limit’ 
‘Enter second X limit’ 

The computer will only try X values within these limits. If you are 
too stingy with these, then not all or perhaps none of the solutions 
may be found. What you are doing is to contribute initial guesswork 
to cut down on the time taken by the computer. If we didn’t allow 
for a modest injection of intelligence in the form of a starting guess, 
even a computer could take a long time to find roots. A computer, 
even the Amstrad, is not endowed with common sense so, in the 
absence of guidance, would have to persevere over wildly extreme 
limits of range. A good start is to try —10 for the first X limit and +10 
for the second. If the solutions are not found on this run, then try 
again with —20 and +20. Unless you have plenty of time to spare, 
resist the temptation to start with, say, —1000 to +1000. The values 
of the X limits are switched automatically by the program if entered 
in the wrong order. 

Having input the trial limits, the next prompt is ‘Enter accuracy 
required (min error)’. A reasonable start would be 0.0001 which 
means that the iterative process will continue until the solutions are 
better than an error of 0.0001. Error inputs outside the range 1E—12 
and 0.1 are rejected. 
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The answers are displayed, together with the range of X over 
which the iteration was carried out. Remember that the results 
should be interpreted with the knowledge that solutions are accur- 
ate to within your stated error. For example, if you know that the 
accurate answer is exactly 2.0, don’t think there is anything wrong if 
you get an answer 1.999999. Remember that only real solutions are 
obtained. Furthermore, if there are many solutions you may not 
find all of them interesting so it is often unnecessary to repeat runs 
with ever wider limits once the desired solution (or solutions) is 
obtained. 


How it works 

When the program is run, it stops at line 90, displays the current 
function (equation) occupying line 100 and outputs the Ready 
prompt. If the equation is satisfactory, the operator types RUN 100 
and the program begins. If not, the equation can be altered, as 
described above, before typing RUN 100. 

The program calls on three major subroutines, GET INPUT, 
CALCULATE SOLUTIONS and DISPLAY SOLUTIONS called at 
lines 190, 320 and 430 respectively. 

The principle adopted is to calculate the value of the function for 
successive integer values of X within the specified range. If a 
solution is an integer then it will be immediately found. However, if 
a sign change is detected for Y values during an X integer interval 
then the solution must reside somewhere within that integer 
interval. 

The program uses an iterative technique known as the bisection 
method to home in on this value. The principle is that the interval is 
halved each time within a loop and the median value input to the 
function. On examination of the resultant sign of Y we can deduce 
whether the value of X was an under or over estimate. The limits of 
the new interval can thus be narrowed down accordingly. There is 
one further complication, the sign order in which the X axis is 
traversed (Y=0) can supply information about the slope of the 
functions graph, if it were to be plotted. This helps us to choose 
which half interval to take as the new interval each time. The 
process is repeated until the solution is correct to within the 
accuracy specified. 


Get input (GOSUB 190) 
The subroutine obtains input from the user and validates it via calls 
to the ‘numerical input validation’ subroutine at line 820. 

The variables assigned are as follows: 
Xmin% =first X value integer limit (—1000 to 1000) 
Xmax%=second X value integer limit (—1000 to 1000) 
accuracy=the minimum error required in the displayed solution (0.1 
to 1E—12). 


Program 4.2 Solving polynomials 


Calculate solutions (GOSUB 320) 

Lines 320 to 330 initialise all the variables used in the subroutine. 
The integer values of X, over the range specified by the user, are 
input into the function and the result tested. If a different sign is 
detected, over one integer interval in line 360, then a non integer 
solution is detected. A call to the subroutine at line 550 is thus forced 
after assigning the interval limits to Xlow and Xhigh. The solution 
obtained by the bisection method, sol, is copied to the array element 
root(N%) and N% incremented ready for the next solution, if any. If 
Y=0 at line 370 then an integer solution has been found at that value 
of X. The corresponding X value of the solution is stored in the array 
element root(N%) and N% incremented, 


Display solutions (GOSUB 430) 

Lines 430 to 460 display preliminary text and display niceties. 
Lines 470 to 500 display all real solutions which are held in the 

array, root(K%). If solutions are not found over the ranges of X 

values originally entered, the word ‘None’ is displayed. 


Non integer solution iteration (GOSUB 550) 
The minimum error E is initialised to 1 in line 550 

The WHILE/WEND loop bisects the interval (Xlow, Xhigh) each 
time and places the median value in the variable XX. The minimum 
error E is halved each time round the loop in line 580. The function 
is evaluated each time and the result placed in the variable, YY, in 
line 590. Depending on the outcome of the comparison of lastY with 
YY in line 600 one from a pair of subroutines is called to assign the 
new bisected interval limits Xlow and Xhigh. The loop exits when 
the minimum error exceeds the specified accuracy. The solution is 
copied into the variable, sol. 


Positive slope (GOSUB 660) 

If the slope of the function is positive and the sign of the function is 
negative then line 660 ensures the right hand half interval is taken as 
the new interval. If the sign of the function is positive then line 670 
ensures the left hand side of the sub interval is taken. 


Negative slope (GOSUB 710) 
This subroutine performs the opposite of the above subroutine 
when the slope is negative. 


Draw line (GOSUB 760) 
This subroutine simply draws a coloured line on the screen when 
called. 


Numerical input validation (GOSUB 820) 
The subroutine is identical to Subroutine 3.6 
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Summary 


1 Angles in trig functions are in radians unless changed by the 
command DEG. 

2 An inverse trig function returns the angle on receipt of the trig 
function. 

3 Inverse trig functions, other than ATN, require programming. 
4 When in doubt, don’t rely on operator precedence. Use brackets. 
5 The commands BIN$ and HEX$ can only convert into string 
forms and therefore cannot be used arithmetically, at least, not 
directly. 

6 All real numbers occupy five memory bytes, irrespective of 
magnitude. 

7 When keyboard INPUT is received in multiple or submultiple 
units, re-scale and work in SI units until the final printout. 

8 The value within the square root of the standard quadratic 
solution is called the discriminant. A negative discriminant indicates 
the roots are unreal. 

9 Polar coordinates are in terms of magnitude and angle. 

10 Cartesian coordinates are in terms of horizontal and vertical 
coordinates. 

11 The factorials, 0! and 1!, are both equal to 1. 

12. Hash functions reduce large numbers to a few randomly 
distributed small numbers. 

13 The output of a hash function can be used to point directly to an 
array location. 

14 There is no guarantee that a number obtained by a hash 
function is unique. 

15 If two hash outputs are the same, they are said to collide. 

16 Hash functions should produce well-spread random numbers 
within a specified range. 

17 Hashing by the division remainder method yields good results, 
particularly if prime numbers are used in the denominator. 

18 Hash functions can only operate on numbers s0, if letters are to 
be hashed, they must be expressed in numerical code form, such as 
ASCII. 

19 Collisions are rare when there are many unoccupied locations, 
but tend to increase as they are progressively filled. 

20 Linear probing is one method used for combating collisions. Ifa 
location is already occupied, the next and the next is tried until a 
vacancy is found. 

21 Linear probing tends to cause clustering. To reduce clustering, 
allow at least 50% more array space than will be used. 

22 Re-hashing is an alternative to linear probing. 








Graphics, graphs and charts 


The value of graphics 


This chapter should help you get to grips with the excellent high 
resolution graphics available on Amstrad machines. Commands 
such as PLOT and DRAW are, in themselves, easy enough to 
learn and use but scaling the parameters to ensure they make full 
use of the screen area, without overstepping the boundaries, is 
more difficult. Several subroutine listings are given in addition to 
three complete programs, all of which should help you to under- 
stand how to manipulate the commands and produce good 
graphical output. 

Pictures convey more than words. Row after row of figures may 
be meaningful, perhaps even exciting, to accountants or mathemati- 
cians, but most of us feel happier if figures are supported by some 
form of picture or diagram. In most cases, the absolute value of 
figures is less important than the relationship between them. An 
expenditure of 200 million in the current year on a particular 
departmental commitment conveys very little to the man in the 
street unless it can instantly be compared with the corresponding 
figure for previous years. A simple diagram shows such relations in 
a forceful manner and, what is more, without demanding too much 
concentration on the part of the viewer. Current affairs programs 
make extensive use of graphics in order to inject a modicum of 
interest into political discussions and arguments. They do so with 
the knowledge that many viewers would either doze off or, worse 
still, switch channels to an imported soap opera unless the drone of 
the speaker is frequently exchanged for an elaborate graph of some 
kind. 

Unfortunately, graphs and charts, like nuclear power, are capable 
of misuse. For example, it is easy to construct a graph in which the 
scale factor, chosen for one of the axes, deliberately disguises features 
which run counter to an argument. Changing a linear scale to a 
logarithmic version or restricting the X axis in order to prevent an 
embarrassing figure appearing are two popular ways of conveying 
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truth in a misleading manner. Another popular ruse for disguising 
the unpalatable is to change the graph from Y to rate-of-change of Y. 
For example, suppose Y, on the vertical axis, represents unemploy- 
ment and X, on the horizontal axis, represents years. If the graph 
begins to rise too steeply, it would be expedient to change the graph 
from actual unemployment to the rate at which unemployment is 
increasing. The graph would now indicate that everything appears 
to be reasonably under control. However, providing graphs and 
charts are interpreted with caution and within an atmosphere of 
suspicion, they are excellent communicating tools. 


Presenting graphical output 


A set of figures can be presented pictorially in a number of ways but 
we Shall limit the discussion to the pie chart, the bar chart, the 
histogram and the cartesian coordinate graph. 


The pie chart 
The pie chart, see Figure 5.1, is based on the circle. 


Segment areas 
proportional 
to magnitude 


Fig 5.1 


It is ideal for portraying limited amounts of information. The size of 
a sector is a measure of the relative magnitude or importance of that 
quantity. If more than, say, eight quantities are to be portrayed, a 
pie chart becomes cramped and of doubtful information value. 


The bar chart 
The bar chart, see Figure 5.2, can portray a larger number of 
separate quantities than the pie chart. 


Presenting graphical output 


Amount 
(magnitude) 





RSS Y 





Fig 5.2 


The magnitude of each quantity is indicated by the height of the 
corresponding bar. Positive and negative values are shown as bars 
above or below the zero line. 


The histogram (see Figure 5.3) 

Bar charts and histograms often look very much alike because 
vertical bars feature in both. However, the height of the bars in a 
histogram corresponds to the number of times a value, or close band 
of values, appear. In other words, it is showing the frequency of data 
items rather than their actual magnitude. 


Frequency 











SSS SSS 


= 


NSS 





DSSS 


Values 
Fig 5.3 _ + 


Notice that unlike the bar chart, all bar heights are positive. A 
moment's thought should convince you that the concept of a 
negative frequency is absurd. On the other hand, there can be 
negative data values so the zero line is an intercept on the X axis 
whereas, in the bar chart, it was on the Y axis. The width (fatness) of 
each bar is proportional to the number of discrete values, over the 
range of X, which have been lumped together to form the bar. One 
bar might represent all X axis values between, say, 25 and 32. If the 
bars are fat, there will only be room for a few and each bar will have 
to serve for a wide spread of values. Conversely, if the bars are thin, 
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we can show many more and each bar will be more truly repre- 
sentative of data frequency. In the limit, as the numbers of bars 
increase, they approach thin vertical lines, each representing only 
one discrete value. 


The cartesian coordinate graph 
The cartesian graph is used for showing how one quantity (called 
the dependent variable), depends on the value of another (called the 
independent variable). The X value, measured along the horizontal 
axis and the Y value, measured along the vertical axis, represent the 
coordinates of a point. A jagged curve can be drawn connecting all 
the plotting points together but, unless a large number of points are 
calculated, the curve can often be misleading. Remember that the 
act of connecting two plotting points by a line is sheer guesswork. 
For example, certain mathematical functions have sharp peaks or 
troughs at specific points on the X axis and could occur bang in the 
middle of two plotting points and so could be missed out altogether. 
This danger deserves emphasis because, later in this chapter, a 
program is presented for plotting graphs of mathematical functions. 
One of the prompt messages asks for the X increment value which is 
equivalent to asking how many X plots are to be used. If you 
respond with too low a value, the curve is drawn quickly, because 
there are fewer calculations, but the plotting points will be wide 
apart and a peak or trough could be missed. It is possible to miss 
interesting features in other ways. For example, the X axis must be 
given limits and, if these limits are too narrow, the features of 
interest could be outside the range of X values. So it is sensible to 
ask for wide limits initially and then run again with narrower limits 
to take in those parts which show evidence of exceptional interest. 
When deciding on the X and Y axis (called the abscessa and ordinate 
respectively) account must be taken of the possibility that either or 
both of them can extend into the negative region. That is to say, the 





Fig 5.4 


Presenting graphical output 


axis lines, in general, will have both positive and negative values. 
The point where they cross is called the origin of the graph and, in 
the general case, will occur at the Y=0 and X=0 points. This gives 
rise to the classical four quadrants, shown in Figure 5.4. 


Quadrant I: both X and Y values positive. 
Quadrant II: X negative and Y positive. 
Quadrant III: X negative and Y negative. 
Quadrant IV: X positive and Y negative. 


The Amstrad graphic commands 


It is assumed that readers will have read and understood, at least in 
part, the information on the various graphics commands contained 
in the User Instructions. It is hoped the following treatment may 
provide some additional help. High resolution graphics on the 
Amstrad have the advantage of sharing the same coordinates in all three 
modes. One individual spot of light is called a pixel. A pixel spot 
produced with, say, X=100 and Y=150 will be in the same screen 
position, irrespective of whether the mode is 0, 1 or 2. 


Pixel size and resolution 

Screen coordinates divide the screen into 640 points horizontally 
and 400 points vertically. The horizontal size of a pixel depends on 
the mode in use: 


Mode 0=4 points per pixel 
Mode 1=2 points per pixel 
Mode 2=1 point per pixel 


The vertical size of a pixel is constant, irrespective of the mode, at 2 
points per pixel. 

Mode 2 gives the highest resolution (640 X positions and 200 Y 
positions) and therefore the smallest pixel size. Unfortunately, only 
two colours are available at any one time. It is a sad fact of life that, 
for a given amount of memory, we can have more colours only if we 
are prepared to sacrifice resolution. We have found that the colour 
monitor is pushed to the limit when trying to resolve Mode 2 
although the monochrome version could probably cope without any 
trouble. 

Mode 1 is, in our view, the wise choice for the default mode. The 
resolution of 320x200 pixel positions is adequate for most purposes 
and well within the capabilities of the Amstrad colour monitor. It 
also allows four different colours to be simultaneously displayed. 

Mode 0 is suitable for those who are intoxicated by bizarre colour 
effects and can make use of the 16 simultaneous colours available. 
Unfortunately, the pixel resolution is down to 160x200. We also 
have to put up with 20 fat characters per line — ideal for distance 
viewing, providing we are prepared to tolerate the rather toytown 
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appearance of the characters. Although of some use in games 
programs, mode 0 is of little use in more serious applications and is 
best avoided altogether. 


Pixel position 

The position of a pixel on the screen is determined by the current 
position of the graphics cursor. There are several commands which 
position or move the graphics cursor and we shall be mentioning 
them later. (The graphics cursor, unlike the character cursor, is 
invisible.) 


The screen origin 

The default position of the graphics cursor is bottom left of the 
screen (X=0, Y=0). The top right hand corner of the screen has the 
absolute coordinates, X=639, Y=399. The origin can be changed by 
use of the command ORIGIN, the default format being: 


ORIGIN X,Y 


Changing the origin is equivalent to adding an offset to the co- 
ordinates. 

The graphics area can extend to the whole of the screen surface or 
it can be restricted by defining a graphic window by including extra 
(optional) parameters in the origin command: 


ORIGIN X,Y,left,right, top,bottom 


Coordinates sent to positions outside a window are ignored without 
invoking an error message. 


Mixing text with graphics 
Normally, text characters are positioned at the current text cursor 
position. However, it is possible to print characters at the graphics 
cursor position by use of the command TAG which is short for Text 
At Graphics. Every time a character is printed, the graphics cursor is 
advanced by eight pixels. The full format is (TAG #stream expres- 
sion) but if TAG only is written, it defaults to stream #0. 

The effect of TAG lasts until it is cancelled by the command 
TAGOFF. 


Plotting points 

A point can be plotted on the screen and the graphics cursor moved 
to that point by the command PLOT X,Y,I where X and Y are 
absolute coordinates. The colour of the point depends on the 
optional parameter ‘I’, defaulting to INK 1. To plot a point at 
coordinates relative to the current cursor position, the command is 
PLOTR X,Y. The coordinates are then in the nature of offsets from 
the current graphics cursor position, rather than absolute screen 
coordinates. 


The Amstrad graphic commands 


Drawing lines 
A line can be drawn by using 


DRAW X,Y, 


The line is drawn from the current cursor position to the absolute 
coordinates X,Y. The colour of the drawn line depends on the ink 
colour specified in the optional ‘I’ parameter, defaulting to INK 1. 
The command DRAWR X,Y,] is similar except that X and Y now 
refer to coordinates relative to the current cursor position so they are 
in the nature of offsets. 


Moving the graphics cursor 

Lines forming a diagram or picture are not always continuous so it is 
often necessary to move the graphics cursor to a new start-of-line 
position. This can be achieved by quoting absolute coordinates of 
the new point in the command MOVE X,Y or by using the 
command MOVER X,Y if relative coordinates are required. 


Finding the graphics cursor 

The graphics cursor is invisible. However, its horizontal position is 
returned by means of XPOS and its vertical position returned by 
YPOS. For example, we can write: 


100 h=XPOS:v=YPOS 


Testing the ink colour 

It is sometimes necessary to find the colour of the ink used at a 

certain X,Y position on the screen. This can be found by the 

function, TEST(X,Y) where X and Y are absolute coordinates. 
TESTR(X,Y) has similar properties but the X,Y coordinates will be 

interpreted relative to the current cursor position, rather than 

absolute. 


Subroutine 5.1 Polygon/circle 


10 REM EXAMPLE: DRAW POLYGON/CIRCLE 

20 MODE 1 

30 X=300: Y=200 

40 INPUT"Enter number of sides";sides% 
SO r%=150:REM radius 


60 CLS:GOSUB 10000 

70 END 

80 ° 

9999 REM DRAW POLYGON/CIRCLE SUBROUTINE 
10000 MOVE X,Y+r% 
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10010 FOR angle=0 TO 2.1*PI STEP (2*#PI/sides%) 
10020 DRAW r%*SIN (angle) +X ,r%*COS (angle) +Y 


10030 NEXT 
10040 RETURN 





Objective:.To draw a polygon with any number of sides. 
Variable names: angle=angle subtended by a polygon side 
X=horizontal plotting coordinate 
Y=vertical plotting coordinate 
sides% =number of sides of the polygon 
r% =radius of circumscribed circle 
Action required before calling with GOSUB: Assign number of polygon 
sides required to sides%. 

Assign screen coordinates to X and Y for the centre of the 
polygon. 

Assign length of polygon radius to r%. 
Action required after RETURN: None. 
How it works: Line 10000 positions the starting point on the circum- 
ference of the polygon. The FOR/NEXT loop sweeps out the angles 
in steps, each equal to the length of one side. Line 10020 should be 
recognised as a polar to cartesian conversion, with offsets X and Y. 
Example calling program: Line 30 fixes, quite arbitrarily, the polygon 
centre on the screen. Line 50 sets the radius to 150, again quite 
arbitrarily. 
Suggested uses: For general purpose graphics. 
Notes: 
side%=1 displays a single spot 
side% =2 draws a line 
side% =3 draws a triangle 
side%=4 draws a square 
side% =5 and above draws a polygon, which approaches a circle as 
the number of sides are further increased to about 20. 


Subroutines 5.2 Polygon/circle (Method 2) 


10 REM EXAMPLE: DRAW POLYGON/CIRCLE 

20 REM (METHOD 2) 

30 MODE 1 

40 X=300: Y=200 

SO INPUT"Enter number of sides";sidesZ% 
60 r%=150:REM radius 


70 CLS:GOSUB 10000 


80 END 

90 ° 

9999 REM DRAW POLYGON/CIRCLE (Rotation) 
10000 MOVE X,Y+r% 

10010 XX=O:YY=r% 





Subroutines 5.2 Polygon/circle (Method 2) 


angle=2#PI/sides% 
thetacos=COS (angle) 
thetasin=SIN (angle) 

FOR NZz=1 TO sides~% 
X1=XX*thetacos-YY*thetasin 


Y¥1=XX*thetasintYY*#thetacos 
XX=X1: YY=Y1 

DRAW X+XX,Y+YY 

NEXT 

RETURN 


Objective: Same as Subroutine 5.1 but where faster execution speed 
is important. 

Variable names: Same variable names as in Subroutine 5.1 with the 
addition of temporary variables X1, Y1, XX and YY. 

Action required before calling with GOSUB: Same procedure as 
Subroutine 5.1. 

Action required after RETURN: None. 

How it works: This subroutine plots a circle by the rotation method. 
The trigonometrical functions are constant so are calculated once 
only before entering the FOR/NEXT loop, in lines 10030 and 10040. 
The standard coordinate rotation formulae, used in lines 10060 and 
10070, sweep out the polygon sides. 

Example calling program: Identical to Subroutine 5.1 call. 

Suggested uses: As Subroutine 5.1 


Subroutine 5.3 Rotation 


10 REM EXAMPLE: ROTATE A SHAPE 
20 REM ABOUT A POINT 
30 MODE 1 

40 DEG 

SO orgX=300: or gY=200: theta=0 
60 INPUT"Enter angle of rotation (degrees) ";angle 
70 number=INT (360/angle) 

80 CLS 

90 FOR NZ=1 TO number 

100 MOVE orgX,orgY 

110 RESTORE 

120 FOR K=1 TO 4 

130 READ X,Y 

140 GOSUB 10000 

150 DRAWR X,Y 

160 NEXT 

170 theta=thetat+angle 

180 NEXT 

190 END 
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200 

210 REM DATA FOR RECTANGLE SHAPE 
220 DATA 150,0 

230 DATA 0,75 

240 DATA -150,0 

250 DATA 0,-75 


260 

9999 REM ROTATION SUBROUTINE 
10000 X1=X*COS (theta) -Y*SIN (theta) 
10010 Y1=X#SIN (theta) +Y*COS (theta) 
10020 X=X1:Y=Y1 

10030 RETURN 





Objective: To rotate an X and Y screen coordinate through a specified 
angle. 

Variable names: 

theta=the angle to which the coordinates are rotated 

X=current X screen coordinate 

Y=current Y screen coordinate 

X1=transformed X screen coordinate 

Y1=transformed Y screen coordinate. 

Action required before calling with GOSUB: Assign the angle to which 
the coordinates are to be rotated to the variable, theta. 

Action required after RETURN: The transformed X and Y values are 
the rotated coordinates. 

How it works: Lines 10000 and 10010 are the standard text book 
formulae for coordinate rotation. The current screen coordinates are 
in X and Y, the rotated coordinates are in X1 and Y1. Line 10020 
copies the transformed coordinates back into X and Y for subse- 
quent use. 

Example calling program: The calling program is a simple demonstra- 
tion on how to rotate any two dimensional shape through a total of 
360 degrees in steps chosen by the user. Degree mode is set in line 
40. 

The default coordinates of the shape to be rotated are placed in 
DATA statements at the foot of the program. The example data 
displays a rectangle. The coordinates, around which the shape is to 
be rotated, are assigned to the variables orgX and orgyY in line 50 
along with the initialisation of the variable theta. The angular step, 
by which the shape is to be rotated, is entered by the user into the 
variable, angle, in line 60. The number of steps necessary at the 
chosen setting for performing a complete 360 degree rotation is 
calculated in line 70 and assigned to the loop delimiter variable, 
number. The FOR/NEXT loop, occupying Lines 90 to 180, draws the 
entire shape at various angles of rotation around the point orgX and 
orgY. Nesting within this outer FOR/NEXT loop is another which 
reads in the DATA for defining the shape. It also transforms each 
coordinate pair to the new angular position by calling on the 


Subroutine 5.3 Rotation 


rotation subroutine. It is essential that the DATA pointer is RE- 
STORED each time before executing this loop. The loop delimiter in 
line 120, in this case 4, should be set to the number of coordinate 
pairs used to define the shape placed in DATA statements. 
Suggested uses: Useful in a variety of animated sequences or com- 
puter art. 

Notes: Although in this example the shape is rotated through a point 
corresponding to the lower left hand corner of a rectangle, it is a 
simple task to change this so that the shape is rotated about its 
centre. 


Subroutine 5.4 Scaling 


10 REM EXAMPLE: SCALE PLOTTING 
20 MODE 1:CLS 


30 XscreenZ=639: YscreenZ=399 

40 Xlow=-PI/2: Xhigh=P1I#2 

SO Ylow=-1: Yhigh=1 

60 X=0:Y=0:GOSUB 10000 

70 MOVE O,Ycoord% 

80 DRAW XscreenZ, Ycoord~” 

90 MOVE Xcoord~z,0 

100 DRAW Xcoord%,Yscreen~z 

110 FOR X=Xlow TO Xhigh STEP 0.05 

120 Y=SIN(X) 

130 GOSUB 10000 

140 PLOT Xcoord%,Ycoord% 

150 NEXT 

160 END 

170 ° 

9999 REM SCALING SUBROUTINE 

10000 Xcoord%Z=CINT (XscreenZ# (X-Xlow) / (Xhigh—-Xlow) ) 
10010 YcoordZ=CINT (YscreenZ* (Y-Ylow) / (Yhigh-Ylow) ) 
10020 RETURN 





Objective: To scale actual values encountered during a program to X 
and Y screen coordinates. 

Variable names: Xcoord% the scaled X screen coordinate. 
Ycoord% = the correspondingly scaled Y screen coordinate. 
Xscreen% =the total number of possible X screen coordinates minus 
one, making up the set graphics window (normally 639). 

Yscreen% =the total number of Y screen coordinates minus one 
making up the graphics window (normally 399). 

Xlow=the minimum X value used in the range of X values to be 
scaled. 

Xhigh=the maximum X value used in the range X values to be 
scaled. 
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Ylow=the minimum Y value in the range of Y values to be scaled. 
Yhigh=the maximum Y value in the range of Y values to be scaled. 
Action required before calling with GOSUB: The variables Xscreen% 
and Yscreen% must be set to the limits of the graphics window 
setting. For a default window this will be Xscreen%=639 and 
Yscreen% =399. 

Set Xlow and Xhigh to the corresponding minima and maxima of 
the X value data range. Likewise, assign the minima and maxima of 
the range of Y values to the variables, Ylow and Yhigh. 

Action required after RETURN: Xcoord% and Ycoord% are the scaled 
screen coordinates for direct use in PLOT commands. 

How it works: The subroutine itself is simple arithmetic, calculating 
each coordinate from: 


value — (min value) 


No. screen coordinates | ————___—__— 
(max value) — (min value) 

Example calling program: The calling program draws axes intersecting 
at the origin and then plots a simple graph of the sine function for X 
between —PI/2 and 2*PI. 

Lines 30 to 50 set up the necessary calling parameters noted 
above. A call to the SCALING SUBROUTINE, after setting X and Y 
to zero in line 60, returns the necessary coordinates for plotting the 
axes intersecting at the graphical origin. Lines 70 to 100 draw the 
axes and the FOR/NEXT loop, lines 110 to 150, plot out the graph 
over the range of X at increments of 0.05. 
Suggested uses: In all cases where two dimensional graphical output 
is required. 
Notes: An alternative to the SCALING SUBROUTINE above is the 
following pair of defined functions. 
DEF FNxcoord(X)=CINT(Xscreen% * (X—Xlow)/Xhigh—Xlow)) 
DEF FNycoord(Y)=CINT(Yscreen%)* (Y—low)/(Yhigh—Ylow)) 
The functions could be used, for example, by changing line 140 to: 
140 PLOT FNxcoord(X),FNycoord(Y) 

This method is used in some of the later programs. 


Subroutine 5.5 Maxima and minima 


REM EXAMPLE: FIND MAXIMA & MINIMA OF ARRAY 
MODE 1:CLS 

DIM Y(150) 

NZ=-1 

FOR X=0 TO PI#¥2 STEP 0.05 


NZ=NZ+1 

Y (NZ) =SIN(X) 

PRINT ROUND (Y (NZ) ,3) 
NEXT 





Subroutine 5.5 Maxima and minima 


100 usedZ=N% 

110 GOSUB 10000 

120 PRINT"Maxima of array="ROUND (high,3) 
130 PRINT"Minima of array="ROUND (low, 3) 
140 END 

150 

9999 REM MAXIMA & MINIMA SUBROUTINE 


10000 high=-1E+38: low=1E+38 
10010 FOR NZ=0 TO used% 
10020 high=MAX (Y (NZ) ,high) 
10030 low=MIN(Y (NZ) ,low) 
10040 NEXT 

10050 RETURN 





Objective: To find the maximum and minimum values present in an 
array. 

Variable names: 

high=the maximum array value 

low=the minimum array value 

N%=loop counter 

used% =a variable set to the highest indexed (used) array element 
Action required before calling with GOSUB: The floating point array, Y, 
must contain the values to be tested. The variable, used%, must be 
set. 

Action required after RETURN: The variables high and low are the 
maxima and minima values respectively and can be re-assigned. 
How it works: Line 10000 initialises the variables high and low. The 
FOR/NEXT loop, lines 10010 to 10040, compares each array value to 
the values of the variables, high and low using the MAX and MIN 
commands. 

Example calling program: The calling program fills the array, Y, with 
the values of SIN(X) over a range 0 to PI/2. After a call to the 
subroutine at line 10000 the maxima and minima are displayed. 
Suggested uses: In conjunction with Subroutine 5.4 can be used for 
fully automatic scaling of axes. 

Notes: The method will ensure that none of the available screen area 
is wasted when plotting a particular graph. 


Subroutine 5.6 Draw axes and pips 
REM EXAMPLE: DRAW GRAPH AXES AND DIVISIONS 


MODE 1:CLS 
Xscreen%Z=539: Yscreen“%=349 


INPUT"Enter X range minima"; Xlow 


INPUT"Enter X range maxima"; Xhigh 
INPUT“Enter Y range minima"; Ylow 
INPUT"Enter Y range maxima"; Yhigh 
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80 GOSUB 10000 

90 PRINT"X units: large="Xgrad" small="Xgrad/S 
100 PRINT"Y units: large="Ygrad" small="Ygrad/S 
110 GOTO 110 

120 END 

130 

9999 REM DRAW AXES AND FIPS SUBROUTINE 

10000 CLS: X=0: Y=0 

10010 GOSUB 11000 

10020 MOVE 1,Ycoord%:DRAW Xscreen%, Ycoord” 
10030 MOVE XcoordZ%,1:DRAW Xcoord%,YscreenZ% 
10040 K=MAX (ABS (Xlow) , ABS (Xhigh) ) 

10050 GOSUB 12000 

10060 Xgrad=R:NZ=-1 

10070 FOR X=P TO Xhigh+Xgrad/10 STEP Xgrad/5S 
10080 NZ=NZ+1 

10090 IF NZ MOD S=0 THEN KZ%=12 ELSE K2Z=4 
10100 GOSUB 11000 

10110 MOVE Xcoord%, YcoordZ-K% 

10120 DRAW XcoordZ, Ycoord“Z+kKz% 

10130 NEXT 

10140 K=MAX (ABS (Ylow) , ABS (Yhigh) ) 

10150 GOSUB 12000 

10160 Ygrad=R:NZ=—-1: X=0 

10170 FOR Y=P TO Yhigh+Ygrad/10 STEP Ygrad/5S 
10180 NZ=NZ+1 

10190 IF NZ MOD S=O0 THEN KZ=12 ELSE K%=4 
10200 GOSUB 11000 

10210 MOVE Xcoord%-KZ, Ycoord~ 

10220 DRAW XcoordZ+KZ, Ycoord~% 

10230 NEXT 

10240 RETURN 

10250 ‘ 

10999 REM SCALING SUBROUTINE 

11000 Xcoord%=CINT (Xscreen%* (X—Xlow) / (Xhigh—-Xlow) ) 
11010 YcoordZ=CINT (YscreenZ* (Y—-Ylow) / (Yhigh—-Ylow) ) 
11020 RETURN 

11030 ° 

11999 REM FIND GRADUATION INCREMENT 

12000 E=0:K=ABS (kK) 

12010 WHILE K<1:K=K*10: E=E-1:WEND 

12020 WHILE K>=10:K=K/10:E=E+1:WEND 

12030 K=—-INT (K+1) 

12040 P=K#10°E:R=1#10°E 

12050 RETURN 








Objective: To draw the axes of a cartesian graph and mark off suitable 





Subroutine 5.6 Draw axes and pips 


graduation pips. Each large division is further divided into five 
subdivisions. 
Variable names: Xscreen%=the maximum X screen coordinate 
(usually 639) 
Yscreen%=maximum Y screen coordinate (usually 399) 
Xcoord% =X coordinate value obtained from scaling subroutine 
Ycoord%=corresponding Y coordinate obtained from scaling 
subroutine 
X=current real X value 
Y=current real Y value 
Xgrad=the real value of each large X axis division 
Ygrad=real value of each large Y axis division 
K%=length of graduation lines when marking off axes divisions 
N%=graduation mark counter 
Xlow=minimum real X value in range 
Xhigh=maximum real X value in range 
Ylow=minimum real Y value in range 
Yhigh=maximum real Y value in range. 
Action required before calling with GOSUB: Xscreen% and Yscreen% 
must be initialised to the graphics window to be used. 

The variables Xlow,Xhigh, Ylow and Yhigh are set as the user 
requires. 
Dependent subroutines or functions 
1 The SCALING SUBROUTINE in line 11000, This is identical to 
Subroutine 5.4. 
2 A FIND GRADUATION INCREMENT subroutine at line 12000. 
This is a subroutine which converts any number in the variable K to 
standard scientific notation. The mantissa is always arranged to be 
>=1 and <10 and is replaced in the variable K. The corresponding 
integer exponent (power of 10) is placed in E. Line 12030 negates the 
integer value of K+1 to ensure all graduations will eventually be 
marked off, irrespective of the original sign or value of K. In line 
12040 the start variable of a FOR/NEXT loop, used to eventually plot 
the graduations, is calculated and stored in P. The corresponding 
STEP parameter is stored in R. 
How it works: The X and Y values are set to zero in line 10000. A call 
to the scaling subroutine in line 10010 finds the coordinates of the 
graphical origin. The X and Y axes are drawn in lines 10020 to 10030. 
It is now necessary to mark off the scale divisions. The variable K is 
set to the absolute maximum value of Xlow and Xhigh. A call is then 
made to the FIND GRADUATION INCREMENT subroutine which 
returns the start and STEP parameters of a FOR/NEXT loop in line 
10070. This loop draws the X axis divisions. The loop start variable is 
set to P and the loop end variable is set to Xhigh. An extra tenth of a 
graduation increment is added in here to null the effects of errors 
introduced by fractional step values. At loop termination, it is 
unlikely that the loop variable will exactly equal the loop end 
variable in these cases. 

Line 10090 sets up the graduation line lengths. Small subdivision 
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lines are drawn at intervals of Xgrad/5 and large division lines (at 
integer powers of 10) are drawn at intervals of Xgrad. 

Lines 10140 to 10230 mark off the Y axis in a similar way. Notice 
that X must be initialised to zero again in line 10160. 
Example calling program: This small program invites the user to 
input Xlow,Xhigh, Ylow and Yhigh. Both ranges of X and Y values 
must include zero and it will be up to the user to ensure this. 
(Programs which follow have such validation built in.) A GOSUB 
10000 call constructs the axes and lines 90 to 100 print out the values 
to be attributed to the large and small graduations of each axis. The 
program locks up in line 110, and requires the escape key to be 
pressed twice in order to end the test. 
Suggested uses: Wherever two dimensional graphical output is re- 
quired with directly readable axes. 
Notes: Similar subroutines are used in the three graph plotting 
programs at the end of this chapter. 


Subroutine 5.7 Draw pie sector 


REM EXAMPLE: DISPLAY A PIE CHART 
MODE 1:DEG:CLS 

X=150: Y=200 
rZ=100:start=0 
sector=0: count=1 

READ title#,items% 
PRINT titles 

FOR NZ=1 TO items% 

READ item$,percentage 
LOCATE 20,NZ+2 

PRINT count"="items 
finish=start+ (percentage/100) *360 
GOSUB 10000 
start=finish 
count=count+1 

NEXT 

finish=360:GOSUB 10000 
LOCATE 20,NZ+2 

PRINT count"=QTHER" 
LOCATE 1,24 

END 


DATA "NODDYLAND PUBLIC EXPENDITURE",5S 
DATA" DEFENCE" , 20 

DATA"ROADS" ,10 

DATA"EDUCATION" , 27 

DATA"HEALTH" , 20 





Subroutine 5.7 Draw pie sector 


280 DATA"STATE INDUSTRY" ,15 

290 

9999 REM DRAW PIE SECTOR SUBROUTINE 

10000 MOVE X,Y 

10010 FOR angle=start TO finish+3 STEP 3 
10020 DRAW rZ#SIN (angle) +X ,r2Z2*COS (angle) +Y 
10030 NEXT 

10040 sector=sector+1 

10050 bisect=(start+finish) /2 

10060 S=SIN(bisect) :C=COS (bisect) 

10070 MOVE rZ#S+X ,rZ¥C+Y 

10080 DRAWR 30#*S,30*C 

10090 IF bisect<200 THEN MOVER 5*S,5*C ELSE MOVER 
40#S , 40*C 

10100 TAG:PRINT sector; 

10110 TAGOFF 

10120 RETURN 





Objective: To display a pie chart where each sector area is propor- 
tional to the magnitude of a data item. 

Variable names: 

X=absolute centre horizontal coordinate 

Y=absolute centre vertical coordinate 

r%=radius of pie chart 

sector=current sector number 

start=angular position at which pie sector starts 

finish=angular position at which current pie sector finishes 
angle=angle subtended by a polygon side (a circle in this subroutine 
is approximated by a 360/3 side polygon) 

bisect=the mid point value of start and finish. 

Action required before calling with GOSUB: Assign values to the 
variables X,Y,r% start and finish. Initialise the variable, sector, to 
zero prior to the first call only. 

Action required after RETURN: Index sector number in separately 
displayed list (optional). 

How it works: The subroutine is similar to Subroutine 5.1 except that 
a line is drawn from the centre of the circle to the circumference to 
denote the start of a sector boundary. Also the finish variable is 
obviously set to a lower value than that of a complete circle. Each 
sector is bisected and a line, of length equal to 30 plot coordinates, is 
drawn projecting away from the centre. The corresponding sector 
number is hung on the end of the line. Due to the relationship 
between the graphics cursor position and the character to be printed 
when using TAG, it is necessary to juggle with the graphics cursor. 
This depends on where the character is to be printed in relation to 
the circumference of the pie chart. Line 10090 ensures a reasonably 
aesthetic display in this respect. 

Example calling program: The calling program displays a pie chart 
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where each sector portrays a percentage of the total. The percentage 
values themselves are stored in DATA statements. Degree mode is 
set in line 20 so that all angular calculations are performed in 
degrees rather than default radians. Certain variables are initialised 
in lines 30 to 50. 

The title of the pie chart, together with the number of data pairs 
are first read in from DATA statements followed by a FOR/NEXT 
loop which reads in each item title and percentage. The start and 
finishing values of the loop are calculated from the percentage data 
and the appropriate sector is drawn by a call to the DRAW PIE 
SECTOR subroutine. At the same time the index number of the 
sector and its title are displayed in list form at the right hand side of 
the screen. On exhaustion of data the loop is terminated. Any 
remaining unused portion of the pie is finally drawn and an entry 
made in the index as ‘other’. Example data is given on the public 
expenditure of ‘Noddyland’. 


Program 5.1 Bar chart 


The program will display information in the form of a conventional 
bar chart. The information is entered into DATA statements at the 
bottom of the program. After initial experiments with the program, 
readers will probably introduce modifications so that the informa- 
tion can be read in from a data tape. This should cause little 
difficulty because some of the subroutines to be described in 
Chapter 7 for creating and loading back a tape file could be used. 


10 REM PROGRAM: BAR CHART 

20 MODE 1 

30 INK 0,0 

40 INK 2,18 

SO XscreenZ=639: YscreenZ=349 

60 DEF FNxcoord(X)=CINT (XscreenZ* (X—Xlow) / (Xhigh-X 
low) ) 

70 DEF FNycoord (Y) =CINT (YscreenZ* (Y—-Ylow) / (Yhigh-Y 
low) ) 

80 GOSUB 310 

90 GOSUB 220 

100 GOSUB 590 

110 GOSUB 410 

120 GOSUB 820 

130 GOSUB 180 

140 CLS: INK 0,1: INK 2,20 

150 END 

160 ° 

170 REM HOLD DISPLAY 





Program 5.1 Bar chart 


K$=""SWHILE K$=""3K$=INKEY$: WEND 
RETURN 

REM FIND MAXIMA & MINIMA OF DATA 
Yhigh=0: Ylow=0 

Xlow=0: Xhigh=items% 

FOR N%Z=0 TO items%-1 
Ylow=MIN(Ylow,B(NZ) ) 

Yhigh=MAX (Yhigh,B(NZ) ) 

NEXT 

RETURN 


REM READ DATA INTO ARRAYS 
RESTORE 

READ titles,items”% 

DIM A#(items~) ,BlitemsZ) 
FOR NZ=0 TO itemsZ-1 

READ label$,K 

A$ (NZ) =l abel $: B(NZ) =K 
NEXT 

RETURN 


REM PLOT AXES & GRADUATIONS 
YZ=FNycoord (0) 

MOVE 1,Y% 

DRAW Xscreenz,Y2%,3 

MOVE 1,1 

DRAW 1,Yscreen~% 

K=MAX (ABS (Ylow) , ABS (Yhigh) ) 
GOSUB 740 

NZ=-1 

FOR Y=P TO Yhigh+R/10 STEP R/S 
N%=NZ+1 

IF NZ MOD S=0 THEN KZ=24 ELSE K2%=8 
YZ=FNycoord (Y) 

MOVE 1,Y% 

DRAW KZ,Y% 

NEXT 

RETURN 


REM PLOT BARCHART 

CLS 

FOR NZ=0 TO itemsZ% 

IF B(NZ)=O THEN 700 

por tZ=FNxcoord (NZ) 
starboardZ=FNxcoord (NZ+0. 8) 
topZ=FNycoord (B(NZ) ) 
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bottomZ=FNycoord (0) 
660 FOR XZ=port% TO starboardZ% 

670 MOVE XZ,bottom~Z 

480 DRAW XZ,topZ,2 

690 NEXT 

700 NEXT 

710 RETURN 

720 ' 

730 REM FIND GRADUATION INCREMENT 

740 E=0:K=ABS (K) 

750 WHILE K<1i:K=K#10:E=E-1:WEND 

760 WHILE K>=10:K=K/10:E=E+1:WEND 

770 K=—-INT (K+1) 

780 P=K#10°E:R=1#10°E 

790 RETURN 

800 ’ 

810 REM LABEL UP DISPLAY 

820 PRINT titles 

830 PEN 3:PRINT"Y units: large="R" small="R/5 

840 PEN 1 

850 FOR NZ=0 TO itemsZ-1 

860 PRINT TAB(NZ*(40/itemsZ)+1) AS(NZ) 5 

870 NEXT 

880 RETURN 

890 ‘ 

900 DATA "MERSEYSIDE NOON TEMPERATURES (deg C)",7 
910 DATA "Sun",8,"Mon",5,"Tue",1,"Wed",-2,"Thur",- 
"Fri",3,"Sat",7 





Using the program 
Assuming the DATA statements have been entered, no keyboard 
activity is needed to operate the program other than typing RUN. 
The first DATA statement must contain the heading of the graph 
in literal text form as shown in the example line 900. This is followed 
by the total number of DATA pairs. This information is needed to 
set a FOR/NEXT loop end variable in order to read in the rest of the 
data. 
Line 910 shows some example data. Note that the format defining 
each bar consists of two parts: 


1 Literal text (abbreviated) describing what the bar stands for. The 
number of characters must be kept down to four at most because 
they have to be displayed on the top of each bar. 

2 The numerical value for each bar. 


The example shows that on Sunday, the Merseyside temperature 
was 8 degrees Celsius, Monday it was 5 degrees, etc etc. 

The bar chart display includes a graduated vertical scale. All 
values are automatically scaled so that bar heights and widths make 


Program 5.1 Bar chart 


full use of the screen area. The program can handle mixtures of 
positive and negative data. 


How the program works 

Principle variables used: A$(item%)=the array storing bar labels 
B(item%)=the array storing the bar values 
N%=loop counter 

Xscreen% =maximum X screen coordinate, set to 639 
Yscreen% =maximum Y screen coordinate, set to 349 
X=an actual X value 

Y=an actual Y value 

Xlow=lowest X value 

Ylow=lowest Y value 

Xhigh=highest X value 

Yhigh=highest Y value 

Subroutine calls: 


READ DATA (GOSUB 310) 


Reads in DATA items and assigns bar labels to the array A$ and 
the values to the array B. 


FIND MAXIMA AND MINIMA (GOSUB 220) 


The FOR/NEXT loop, occupying lines 240 to 270, finds these 
values with the help of the BASIC commands MAX and MIN. The 
subroutine is similar to that of Subroutine 5.5 


PLOT BAR CHART (GOSUB 590) 


This subroutine consists of a nested pair of FOR/NEXT loops. The 
outer one controls each complete bar plot while the inner one 
controls the construction of each individual bar. If a particular bar 
value happens to be zero then the construction loop is bypassed in 
line 610. A bar is drawn by drawing a number of parallel lines scaled 
to the value of the bar. The top and bottom vertical Y coordinate 
limits are stored in the variables top% and bottom%. The variables 
port% and starboard% are the X coordinate values of the left and 
right hand sides of the bar respectively. The width of each bar is 
scaled to 0.8 times the distance between successive bars. This 
ensures a healthy gap between each. The scaling functions in lines 
60 and 70 are frequently used throughout the subroutine. 


PLOT AXIS AND GRADUATIONS (GOSUB 410) 


This subroutine is a cut down version of Subroutine 5.6 described 
earlier since only the Y axis needs to be graduated. The same 
subordinate subroutines are brought into use although the scaling is 
managed by the defined functions, shown in lines 60 and 70. 


LABEL UP DISPLAY (GOSUB 820) 
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This is a simple routine which displays the value of the large and 
small graduation intervals for both X and Y axes. The FOR/NEXT 
loop, lines 850 to 870, display the labels at the top of each individual 
bar. 


HOLD DISPLAY (GOSUB 180) 


This is a wait-for-key-press action. 


Program 5.2 Histogram/spectrum plotter 


The distinction between a bar chart and a histogram was explained 
earlier. The figures to be displayed in histogram form are again 
placed in DATA statements but, as mentioned in the previous 
program, it would be a simple matter to convert to data tape entry. 


REM PROGRAM: HISTOGRAM/SPECTRUM PLOTTER 
20 MODE 1 


30 INK 0,0 

40 INK 2,18 

SO XscreenZ=639: YscreenZ=349 

60 DEF FNxcoord(X)=CINT (XscreenZ* (X-Xlow) / (Xhigh-X 
low) ) 

70 DEF FNycoord(Y)=CINT (YscreenZ* (Y-Yl ow) / (Yhigh-Y 
low) ) 

80 GOSUB 780 

90 GOSUB 530 

100 GOSUB 600 

110 GOSUB 1210 

120 GOSUB 880 

130 GOSUB 280 

140 CLS 


150 PRINT"Group data into different ranges (Y/N)" 
160 GOSUB 440 


170 IF K$="Y" THEN ERASE A:GOTO 90 
180 CLS: INK 0,1: INK 2,20 

190 END 

200 ° 

210 REM DRAW LINE 

220 PEN 3 

230 PRINT STRINGS (40,CHR$(154)); 
240 PEN 1 

250 RETURN 

260 ° 

270 REM HOLD DISPLAY 

280 K$="" "WHILE K$="":KS=INKEY$: WEND 
290 RETURN 





300 
310 
320 
330 
340 
350 
360 


370 
380 


390 
400 
410 
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REM TITLE 

CLS 

LOCATE 1,2 

GOSUB 220:PEN 2 

PRINT TAB(12)5 "HISTOGRAM PLOTTER" 
GOSUB 220:PEN 1 

RETURN 


REM NUMERICAL INPUT VALIDATION 
INPUT K 
IF typeZ=0 AND K<>INT(K) THEN PRINT"Input not 


an integer":GOTO 400 


420 


IF K<low OR K>high THEN PRINT"Input out of ran 


ge":GOTO 400 
RETURN 


430 
440 
450 
460 
470 
480 
490 
500 
510 
520 
530 
540 
550 
560 
570 
580 
590 
600 
610 
620 
630 
640 
650 
660 


670 
680 


690 
700 
710 
720 
730 
740 
750 





REM GET YES/NO RESPONSE 
ks="" 

WHILE K$<>"Y" AND K$<>"N" 
K$=INKEY$: K$=UPPER$ (K$) 
WEND 

RETURN 


REM ENTER PARAMETERS 

GOSUB 320 

PRINT"Group data into how many ranges (5-639)" 
typeZ=0: 1low=5: high=639:GOSUB 400 

bandsZ=K 

RETURN 


REM TABULATE DATA 

DIM A(bandsZ) 

Xlow=0: Xhigh=0 

Ylow=0: Yhigh=0 

GOSUB 320:PRINT"TABULATING DATA (please wait)" 
FOR N%=1 TO items” 
Xlow=MIN(Xlow,B(NZ) ) 

Xhigh=MAX (Xhigh,B(NZ) ) 

NEXT 
Xhigh=Xhigh+ (Xhigh—X1 ow) / (bandsZ-1) 
bandr ange= (Xhigh-X1low) /bands~% 

FOR NZ=1 TO items% 

PZ=ABS (INT ( (B (NZ) —Xlow) /bandr ange) ) 
AC(PZ) =A(PZ) +1 

Yhigh=MAX (Yhigh,A(PZ) ) 

NEXT 

RETURN 
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760 

770 REM READ DATA INTO ARRAY 

780 RESTORE 

790 READ items~ 

800 DIM Blitems~%) 

810 FOR NZ=1 TO items% 

820 READ K 

830 B(NZ)=K 

840 NEXT 

850 RETURN 

8460 ° 

870 REM PLOT AXES & GRADUATIONS 

880 YZ=FNycoord (0) 

890 XZ=FNxcoord (0) 

900 MOVE 1,Y% 

910 DRAW XscreenZ,YZ%,3 

920 MOVE X%,1 

930 DRAW XZ, YscreenZ% 

940 K=MAX (ABS (Xlow) , ABS (Xhigh) ) 

950 GOSUB 1400 

960 NZ=-1 

970 FOR X=P TO Xhigh+R/10 STEP R/5S 

980 NZ=NZ%+1 

990 IF N% MOD 5=0 THEN K%Z=24 ELSE K%=8 
1000 XZ=FNxcoord (X) 

1010 MOVE X%,Y% 

1020 DRAW X%,YA+K% 

1030 NEXT 

1040 XZ=FNxcoord (0) 

1050 K=MAX (ABS (Ylow) , ABS (Yhigh) ) 

1060 GOSUB 1400 

1070 NZ=-13 Xgrad=R 

1080 FOR Y=P TO Yhigh+R/10 STEP R/5 
1090 NZ=NZ+1 

1100 IF NZ MOD S=0 THEN K%=24 ELSE KZ=8 
1110 YZ=FNycoord (Y) 

1120 MOVE X%-KZ,Y% 

1130 DRAW X%+K2Z,Y% 

1140 NEXT 

1150 PRINT"X units: large="Xgrad" small="Xgrad/5 
1160 PRINT"Y units: large="R" small="R/5 
1170 PEN 3:PRINT"Y axis:FREQUENCY of data within X 
range":PEN 1 

1180 RETURN 

1190 

1200 REM PLOT HISTOGRAM 

1210 CLS 
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1220 PZ=-1 

1230 FOR N=Xlow TO Xhigh STEP bandrange 
1240 PZ=P2+1 

1250 IF A(PZ)=0 THEN 1360 

1260 limit=N+ (1*#bandrange) 

1270 port%=FNxcoord (N) 

1280 starboard%=FNxcoord (limit) 
1290 top%=FNycoord (A(P%) ) 

1300 bottom%Z=FNycoord (0) 

1310 colZ=P% MOD 2+1 

1320 FOR X%Z=port% TO starboard% 
1330 MOVE X%,bottom~ 

1340 DRAW X%Z,top%,col% 


1350 NEXT 
1360 NEXT 


1370 RETURN 
1380 ° 


1390 REM FIND GRADUATION INCREMENT 

1400 E=0:K=ABS (K) 

1410 WHILE K<1:K=K#10:; E=E-1: WEND 

1420 WHILE K>=10:K=K/10:E=E+1:WEND 

1430 K=-INT (K+1) 

1440 P=K#¥10°E: R=1#10°E 

1450 RETURN 

1460 ° 

1470 DATA 50 

1480 DATA 4,46,-3,8,7,-1,46,3,5,6,7,9,2,—-3,4, 
9 9 yO gg 9 79 749494 Fy 24 By Fy 7g 4 4q 4-3 y-3y 
97 9441 595-3,4454,35 





Using the program 

Begin by trying out the program using the example DATA shown at 
the bottom of the program. When the first prompt appears, ‘Group 
data into how many ranges (5-639)’, try entering 15, just to see what 
happens. This will group all data into 15 bands and display them as 
bars of varying heights. To analyse what is happening, note that the 
example data includes numbers within the range —5 to +9. This is a 
range of 15, which is the number of bands we asked for. Now count 
up how many times each number appears. For example, the 
number 6 appears more often than the others, 10 times in fact, so we 
expect the bar with an X value of 6 should be the highest bar in the 
display. On the other hand, the figures —5 and 1 only appear once 
so these bars will be the shortest. Because the range of numbers in 
the above example was 15, we chose to group the numbers into 
15 bands to simplify the task of checking out the program. In 
practice, there is no need to ensure that the number of bands 
matches the range of numbers. In some cases, particularly when the 
data is the result of repeated measurements of the same physical 
quantity, the results will consist of a large number of values most of 
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them closely grouped around a mean value. There could be several 
tens of separate values, most of them within a range, say, 20 to 25. 
The outline of the histogram will often resemble the typical bell 
shape, characteristic of a Gaussian distribution. 


How the program works 

Principle variables used: 

B(items%)=the array into which data items are read 
A(band%)=the array holding the frequency of values within each 
band grouping 

Xscreen% =maximum X screen coordinate, set to 639 

Yscreen% =maximum Y screen coordinate, set to 349 

X=an actual X value 

Y=an actual Y value 

Xlow=lowest X value 

Ylow=lowest Y value 

Xhigh=highest X value 

Yhigh=highest Y value 

bands% =number of bands into which the data is to be grouped. 
Subroutine calls: Many of the subroutines should be quite familiar by 
now. Itemised below are newcomers: 


READ DATA (GOSUB 780) 
The subroutine reads all the data into array B(N%). 
ENTER PARAMETERS (GOSUB 530) 


Issues the prompt ‘Group data into how many ranges (5-639)’. 
The user’s response is entered into the variable, bands%. The 
subroutine uses subordinate subroutines TITLE and INPUT 
VALIDATION. The input validation rejects non integers and 
numbers outside the range 5 to 639. 


TABULATE DATA (GOSUB 600) 


After DIMensioning the array A(bands%) and initialising, the 
program title is displayed followed by the message ‘TABULATING 
DATA (please wait)’. The maximum and minimum values of the 
data array, B, are found (using the special BASIC commands MAX 
and MIN) and are assigned to Xhigh and Xlow. As it stands, we 
cannot use the value of Xhigh because we have not left enough 
room to display the last band. Lines 680 and 690 ensure that Xhigh is 
increased by one bandwidth. The FOR/NEXT loop, lines 700 to 740, 
perform a count of data items falling within each particular range 
of X. The count of data items lying within each particular band 
range is allocated its own individual array element, A(P). Within the 
loop, Yhigh is set to the highest value stored in the array, A. This 
would correspond to the height of the maximum frequency bar to be 
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displayed. The variable, Ylow will always be zero and is initialised 
at the head of the subroutine. 
Only the one subordinate subroutine, TITLE, is involved. 


PLOT HISTOGRAM (GOSUB 1210) 


This subroutine is, in many ways, similar to its analogue in 
Program 5.1. The main difference is that adjacent bars may touch. 
To overcome this, alternate bars are printed in a different colour. 
However, some bars may not be constructed because there are no 
data items within the band range. If you prefer to have a visible gap 
between each bar then change the multiplier of the variable, 
bandrange, in line 1260 from one to say 0.9 


PLOT AXIS AND GRADUATIONS (GOSUB 880) 


This subroutine is more or less the same as that of Subroutine 5.6 
except that defined functions are used for the scaling instead of the 
SCALING subroutine. 


The subordinate subroutine FIND GRADUATION INCREMENT 
is involved. 


HOLD DISPLAY (GOSUB 280) 
This is a wait-for-key-press action. 
GET Y/N RESPONSE (GOSUB 460) 


Used in response to the prompt ‘Group data into different ranges 
(Y/N)’. If the response is Y, the program can be run again from the 
top. Otherwise, the program will END. 


Plotting graphs and functions 


Plotting the graph of a mathematical function, even a relatively 
simple one like X sin 3X is, to say the least, tedious and time 
consuming. To start with, there is the problem of scaling the axis to 
make sure that turning points (humps and dips) in the curve are 
within the Y axis limits. Unless you have some familiarity with 
calculus, this can only be done by laborious trial and error pro- 
cesses. Very often, only the rough shape of the graph is of interest 
and the absolute values of the plotting points would not be needed 
anyway. The Amstrad CPC464/664, with its high resolution 
graphics capability together with a rich stock of graphic commands 
can easily do all the work in a few seconds. 


115 


116 


Graphics, graphs and charts 


Before discussing the program, we should be aware of the 
difference between continuous and discontinuous curves. Most com- 
monly used functions are continuous, in the sense that a smooth 
curve can be drawn through all plotting points. A discontinuous 
curve is one which either has gaps or attains values which converge 
towards plus or minus infinity (called asymptotic curves). For ex- 
ample, the function 1/X is discontinuous because as X gets larger 
and larger, the function gets smaller and smaller and, in the limit, 
approaches zero. Conversely, as X gets smaller and smaller, the 
function approaches a value approaching infinity, the classic ex- 
ample being the graph of the tangent. The function, TAN X, 
approaches infinity as the angle X approaches 90 degrees but 
changes dramatically to minus infinity as the angle trips over the 90 
degree point. (You will find it important to distinguish between 
continuous and non-continuous functions when _ operating 
Program 5.3). 
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10 REM PROGRAM: FUNCTION PLOTTER 

20 MODE 1i:INK O,1: INK 2,20 

30 GOSUB 590:PRINT"CHANGE FUNCTIONS (‘follow instru 
ctions)":GOSUB 590 

40 PRINT"Current DEFined functions are listed” 

50 PRINT:PRINT"Modify the program lines as require 


60 PRINT"but only to the right hand side of =" 

70 PRINT:PRINT"When satisfied type the command RUN 
100 

80 GOSUB 590:PRINT 

90 LIST 100-120 

100 DEF FNfirst(y)=SIN(X) 

110 DEF FNsecond (y) =COS (X) 

120 DEF FNthird(y)=SIN(X)+COS(X) 

130 ON ERROR GOTO 2300 

140 DIM A(642,3) , top (2) ,bottom(2) 

150 MODE 1 

160 INK 0,O: INK 2,18 

170 paraflag%Z=0 

180 GOSUB 700 

190 LOCATE 1,8 

200 PRINT"MENU" 

210 LOCATE 1,11 

220 PRINT"(1) Change functions or End program" 

230 PRINT"(2) Enter parameters and tabulate" 

240 PRINT"(3) Plot ist function" 

250 PRINT"(4) Plot 2nd function" 

260 PRINT"(S5) Plot 3rd function" 
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270 PRINT"(6) Plot ist & 2nd functions" 

280 PRINT"(7) Plot ist & 3rd functions" 

290 PRINT"(8) Plot 2nd & 3rd functions" 

300 PRINT"(9) Plot ist,2nd & 3rd functions" 

310 LOCATE 1,22 

320 CHOICES="1234546789":GOSUB 410 

330 IF SEL%Z>2 AND paraflagZ=0O THEN PRINT"No parame 
ters given (Select option 2)":GOSUB 650:RUN 100 
340 CLS 

350 ON SELZ GOSUB 20,1010,1260,1320,1380,1440,1510 
»1590,1440 

360 IF SELZ>2 THEN K$=""]WHILE K$="":K$=INKEY$: WEN 
D 

370 GOTO 180 

380 END 

390 ' 

400 REM MENU SELECTION VALIDATION 

410 PRINT"Select option"; 

420 SELZ=0:WHILE SELZ=0 

430 KS=UPPERS (INKEY$) 

440 IF K$<>"" THEN SELZ=INSTR (CHOICES ,K#) 

450 WEND 

460 RETURN 

470 ' 

480 REM VALIDATE AXES LIMITS 

490 A=0: B=0 

500 WHILE A=B 

S10 PRINT"Enter first limit "M#: INPUT A 

520 PRINT"Enter second limit "M%: INPUT B 

530 WEND 

540 C=MIN(A,B) : D=MAX (A,B) 

550 IF C>O OR D<O THEN PRINT"REJECTED: Zero origin 
excluded in range":GOTO 490 

560 RETURN 

570 ° 

S80 REM DRAW LINE 

590 PEN 3 

600 PRINT STRINGS (40, CHR$ (154) ) 5 

610 PEN 1 

620 RETURN 

630 ' 

640 REM HOLD DISPLAY 

650 PRINT"Press SPACE bar to continue" 

660 K$="" WHILE K$#< >CHR$ (32) :KS=INKEY$: WEND 

670 RETURN 

680 ° 

690 REM TITLE 





118 


Graphics, graphs and charts 






















700 
710 
720 
730 
740 
750 
760 
770 
780 
790 
an i 
800 
ge": 
810 
820 
830 
840 
850 
840 
870 
880 
890 
900 
910 
920 
930 
940 
950 
LSE 
960 
970 
980 
990 


1040 
1050 
1060 
1070 
1080 
1090 
1100 
1110 
1120 





1000 REM TABULATE DATA INTO RECT ARRAY 

1010 GOSUB 910:CLS 

1020 GOSUB 590:PRINT”"TABULATING DATA (please wait) 
":;GOSUB 590 

1030 inc=(Xhigh-Xlow) / (resZz*64) 





CLS 
LOCATE 1,2 

GOSUB 590:PEN 2 

PRINT TAB(12)3;"FUNCTION PLOTTER" 

GOSUB 590:PEN 1 

RETURN 

REM NUMERICAL INPUT VALIDATION 

INPUT K 

IF typeZ=0 AND K<>INT(K) THEN PRINT"Input not 
nteger":GOTO 780 

IF K<low OR K>high THEN PRINT"Input out of ran 
GOTO 780 

RETURN 


REM GET YES/NO RESPONSE 
Ks= ou 


WHILE K$<>"Y" AND K$<>"N" 
K#=INKEY%: K$=UPPERS (K$) 
WEND 

RETURN 


’ 


REM ENTER PARAMETERS 

GOSUB 590:PRINT"ENTER PARAMETERS": GOSUB 590 
M$="X axis":GOSUB 490: Xlow=C: Xhigh=D 
PRINT"Any discontinuities in functions (Y/N)" 
GOSUB 840 

IF K$="Y" THEN flag%=O0:M$="Y axis":GOSUB 490 E 
flag%Z=1 

PRINT"Enter resolution reqd (1-10)" 

typeZ=0: low=1:high=10:GOSUB 780:res%=K 

RETURN 
















FOR NZ=0 TO 2 

top (NZ) =-1E+38:s bottom (NZ) =1E+38 
NEXT 

NZ=0 

FOR X=Xlow TO Xhightinc/2 STEP inc 
NZ=NZ+1 

A(NZ,0) =FNfirst (xX) 

top (0) =MAX (top (0) ,A(NZ,0)) 

bottom (0) =MIN(bottom(0) ,A(NZ,0) ) 
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A(NZ,1)=FNsecond (X) 

top (1) =MAX (top (1) ,A(NZ,1)) 
bottom(1)=MIN(bottom(1) ,A(NZ,1)) 
A(NZ,2) =FNthird (X) 

top (2) =MAX (top (2) ,A(N%, 2) ) 
bottom(2)=MIN(bottom(2) ,A(NZ,2)) 
A(NZ,3) =X 

NEXT 

used“Z=NZ% 

paraflagZ=1 

RETURN 

REM PLOT FUNCTION 1 
Ylow=bottom (0): Yhigh=top (0) 
GOSUB 1730 

graphZ%=0:GOSUB 2100 

RETURN 

REM PLOT FUNCTION 2 
Ylow=bottom(1):Yhigh=top (1) 
GOSUB 1730 

graphZ=1:GOSUB 2100 

RETURN 


REM PLOT FUNCTION 3 
Ylow=bottom(2) : Yhigh=top (2) 
GOSUB 1730 

graph%=2:GOSUB 2100 

RETURN 

REM PLOT FUNCTIONS 1 & 2 
Ylow=MIN(bottom(0) ,bottom(1)) 
Yhigh=MAX (top (0) , top (1) ) 
GOSUB 1730 

FOR graphZ=0 TO 1:GOSUB 2100:NEXT 
RETURN 


REM PLOT FUNCTIONS 1 & 3 
Ylow=MIN(bottom(O) ,bottom(2)) 
Yhigh=MAX (top (0) , top (2) ) 
GOSUB 1730 

FOR graphZ=0 TO 2 STEP 2 
GOSUB 2100: NEXT 

RETURN 


’ 


REM PLOT FUNCTIONS 2 & 3 
Ylow=MIN(bottom(1) ,bottom(2)) 
Vhigh=MAX (top (1) , top (2) ) 
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GOSUB 1730 
FOR graph%=1 TO 2:GOSUB 2100:NEXT 
RETURN 


REM PLOT FUNCTIONS 1,2 & 3 

Ylow=MIN (bottom (0) ,bottom(1) ,bottom( 
Yhigh=MAX (top (0) ,top (1) , top (2) ) 
GOSUB 1730 

FOR graphz=0 TO 2:GOSUB 2100:NEXT 
RETURN 


REM PLOT AXES & GRADUATIONS 

IF flag%Z=0 THEN Ylow=C: Yhigh=D 
IF Ylow>O THEN Ylow=0 

IF Yhigh<O THEN Yhigh=0 

X=0: Y=0:GOSUB 2250 

MOVE 1,Ycoord% 

DRAW 640, YcoordZ,1 

MOVE Xcoord%,1 

DRAW Xcoord%,399 

K=MAX (ABS (Xlow) , ABS (Xhigh) ) 
GOSUB 2170 

MOVE 40,390: TAG 

PRINT"X units:"3R; 

TAGOFF 

NZ=-1 

FOR X=P TO Xhigh+R/10 STEP R/5 
NZ=NZ+1 

IF N%Z MOD 5=0 THEN K%Z=12 ELSE K7%Z=4 
GOSUB 2250 

MOVE Xcoord%, Ycoord%-K% 

DRAW Xcoord%, Ycoord%Z+kK% 

NEXT 
K=MAX.(ABS (Ylow) ,ABS (Yhigh) ) 
X=0:GOSUB 2170 

MOVE 40,370: TAG 

PRINT"Y units: "3R;3 

TAGOFF 

NZ=-1 

FOR Y=P TO Yhigh+R/10 STEP R/5 
NZ=NZ+1 

IF NZ MOD S=0 THEN KZ%=12 ELSE K%Z=4 
GOSUB 2250 

MOVE Xcoord%-KZ, Ycoord% 

DRAW Xcoord%+KZ, Ycoord% 

NEXT 

RETURN 


. 
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2090 REM PLOT GRAPH 

2100 FOR NZ=1 TO used% 

2110 X=A(NZ,3) 3 Y=A(NZ,graph~%) 

2120 GOSUB 2250 

2130 PLOT Xcoord%, Ycoord%,graph%+1 

2140 NEXT 

2150 ° 

2160 REM FIND GRADUATION INCREMENT 

2170 E=0:K=ABS (K) 

2180 WHILE K<1:K=K#10:; E=E—-1:WEND 

2190 WHILE K>=10:K=K/10:E=E+1:WEND 

2200 K=-INT(K+1) 

2210 P=K*¥10°E: R=1#10°E 

2220 RETURN 

2230 ’ 

2240 REM SCALE TRANSFORMATION 

2250 Xcoord“%Z=CINT (639% (X—Xlow) / (Xhigh—-X1low) ) 

2260 Ycoord“Z=CINT (399% (Y—-Ylow) / (Yhigh-Y1l ow) ) 

2270 RETURN 

2280 ’ 

2290 REM ERROR HANDLING ROUTINE 

2300 IF ERL=2260 AND ERR=6 THEN Ycoord2%=401: RESUME 
2270 

2310 IF ERR=18 THEN CLS:PRINT"Check functions" 
2320 IF ERL>1010 AND ERL<1230 AND (ERR=6 OR ERR=11 
) THEN RESUME 1200 ELSE CLS:PRINT"Cannot plot this 
function" 

2330 GOSUB 4650:RESUME 180 





Using the program 

On first RUNing the program, some preliminary instructions are 
displayed for changing the resident functions for those of your own. 
We shall not repeat details of this procedure because they are 
exactly the same as described for Program 4.2 in the previous 
chapter. When you have changed them, or left them alone as the 
case may be, the program will come to a stop, waiting for you to 
enter RUN 100 and gain the menu. The program has facilities for 
plotting up to three functions which can be displayed separately or 
in any combination. Providing the function has no discontinuities 
(and you will be asked whether or not it has), you have no need to 
worry about the function values because the scaling is calculated 
automatically by the program. In the first instance, the program 
requires some parameters before it can start plotting, so Option 2 
will be the first choice. In fact options other than 1 or 2 are 
disallowed at the first menu selection. Only after the tables have 
been generated can other options be selected. Option 2 unleashes 
the following prompts: 

The first two are for the axis X limits: 
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1 ‘Enter first limit’ 
2 ‘Enter second limit’ 


Suppose you want the curve of a particular function between X 
values of —3 and +4. In reply to the prompt ‘Enter first limit’ you 
would enter —3. In reply to the second prompt, ‘Enter second limit’, 
you would enter 4. It doesn’t matter if you enter the higher limit first 
because the program will reverse them automatically. However, 
you must ensure that the limits you give enclose the zero origin. For 
example, if you give the lower limit as 2 and the higher limit as 6 the 
error message ‘REJECTED: Zero origin excluded in range’ will 
appear and you must re-enter. 

3 ‘Any discontinuities in function (Y/N)’ 

Assume you answer with N. 

4 ‘Enter resolution required (1-10)’ 


If you enter high numbers, there will be more plotting points 
(causing a smoother curve) but the tabulation time will be high. 
Initially, most graphs will givea satisfactory display with a resolution 
of 1. You can always tabulate again using a higher number. 


Using the built in functions 
To enable you to get a preliminary feel of the program, to become 
used to the screen messages and to experiment with different limits, 
stick with the three functions, SIN(X), COS(X) and SIN(X)+COS(X) 
already in the machine at lines 110, 120 and 130. If you are rusty on 
trigonometry, start with the limits 0 and 6.28 because this will give 
you a nice looking graph extending over one complete cycle of a sine 
wave. The higher the limits, the more complete cycles will crowd 
into the screen which will degrade the appearance and readability. 
Options 3, 4 or 5 will show you any one of the three graphs 
separately. Options 6, 7, 8 or 9 will allow various mixtures of the 
three to be displayed on the same axes. When more than one graph 
is displayed, the automatic scaling will make sure that all curves lie 
within the axis. This is because the curves are checked for those 
which have the largest magnitude maxima and minima before the Y 
axis is scaled. In some circumstances, depending on the mix, one of 
the curves may occupy only a small part of the display because the 
one that hogs most of the screen must decide the scaling. 


Handling discontinuous curves 

If you answered ‘Y’ to the prompt ‘Any discontinuities in function 
(Y/N)’, you will be asked to give Y limits as well as X limits. Your 
answer may be either sheer guesswork or, if you have some 
knowledge of the function, a reasonable estimate. All the input 
validation techniques that are applicable to the X axis limits are 
again used. 


Tabulation time 
After the prompts for parameters have been answered, the screen 
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clears before displaying the message “TABULATING DATA (please 
wait)’. The higher the figure you entered for resolution, the longer 
you must wait before the graph/s appear. Waiting time also depends 
on the complexity of the functions. In general, expect to wait for 
seconds, rather than minutes. You have the opportunity of chang- 
ing the X limits and the resolution without changing the functions. 
Extensive error checking is built in, including the rejection of illegal 
functions. 


How the functions are displayed 
The X and Y axes are drawn and unit and 1/5 unit pips added. The 
function curve (or curves) are then drawn, each with a different 
colour for distinguishing purposes. 

The numerical scaling factors for the X and Y pips are displayed in 
round powers of ten. The drawing speed depends, as you might 
expect, on the resolution demanded. 


How the program works 

If you decide to key in the program, leave out the ON ERROR 
GOTO in line 130 until you have cleared all remaining syntax errors, 
otherwise you will receive no error guidance. A simplified flow 
chart is shown in Figure 5.5 which should help you to follow the 
overall structure. 

The program contains no special tricks, and consists almost 
entirely of separate subroutines, only a few of which justify detailed 
explanation. 

Variables used 

A(N%,0)=array element holding a single Y value of 1st function 

A(N%,1)=array element holding a single Y value of 2nd function 
A(N%,2)=array element holding a single Y value of 3rd function 
A(N% ,3)=array element holding a single X value of all functions 
top(0)=maximum Y value of graph 1 

bottom(0)=minimum Y value of graph 1 

top(1)=maximum Y value of graph 2 

bottom(1)=minimum Y value of graph 2 

top(2)=maximum Y value of graph 3 

bottom(2)=minimum Y value of graph 3 

Xcoord% =X plot coordinates after scaling 

Ycoord% =Y plot coordinates after scaling 


TABULATE DATA (GOSUB 1010) 


Tasks performed: 

1 Calculate maximum and minimum Y values of each of the three 
functions. 

2 Calculate the Y values of all three functions and the X value 
common to all three and tabulate the results in the 4 by 642, two 
dimensional array. 


PLOT FUNCTION (GOSUB 1260, 1320, 1380, 1440, 1510, 1590, 1660) 
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START 













YES 
Change Rrociions 4 5 







RUN 100 


Display menu 








NO 









Enter parameters 


Tabulate data 





Display graphs 


Fig 5.5 
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Menu options 3 to 9 offer various combinations of the three 
graphs. A separate subroutine is used for each option. In each case 
the Y axis minima and maxima are set, according to the particular 
graph or combination of graphs to be displayed. This ensures that 
none of the available screen area is wasted. They each call on the 
following subordinate subroutines: 


PLOT AXIS AND GRADUATIONS (GOSUB 1730). 


This is similar to Subroutine 5.6 and performs the following tasks: 


1 Draws the X and Y axis. 

2 Adds unit pips and 1/5 units to each axis after first calling the 
subordinate subroutine FIND GRADUATION INCREMENT at 
line 2210. 

3 Prints the scale labels of the units in round powers of ten. 


PLOT GRAPH (GOSUB 2140) 


The raw X and Y tabulated values are unsuitable for direct 
application to the high resolution display because many of the 
values would be off the screen. In other words, the X and Y plotting 
values must be disciplined before they can become true X co- 
ordinates and Y coordinates. This task is relegated to the scale 
transformation subroutine at line 2290 which is identical to Sub- 
routine 5.4 described earlier. 


Summary 


1 Charts and graphs concerned with statistics often mislead in a 
truthful way. 

2 Pie charts are ideal for portraying the values of a small number of 
items. 

3 Bar charts are suitable for displaying the values of a larger 
number of items. 

4 A histogram may look similar to a bar chart but is used to show 
the frequency distribution, rather than the magnitude, of data 
items. 

5 All bar heights in a histogram represent positive values even 
though the data items can be positive or negative. 

6 A cartesian coordinate graph plots functions of Y against X 
values. 

7 A discontinuous function is one that tends towards infinity at 
one or more points in the graph. 

8 Important features of a function can be missed by either: 

(a) using plotting points too far apart (low resolution) or 

(b) an unwise choice of X range. 
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9 In mathematics, the graph origin is at the point where X=0, Y= 
0. 

10 A pixel is the smallest screen blob possible for the particular 
Mode in use. 

11 The position of a pixel on the screen is determined by the 
(invisible) graphics cursor. 

12. The screen origin defaults to bottom left of the screen but can be 
changed with the command ORIGIN. 

13 The screen origin and the mathematical graph origin will not 
necessarily coincide. 

14 Text can be printed at the graphics cursor position while the 
command TAG remains in force. 

15 The effects of TAG immobilises the normal text cursor until 
such time as it is cancelled by the command TAGOFF. 








Music 


Music and noise 


Many of us use the word ‘music’ in everyday speech to describe 
sounds we like and the word ‘noise’ to describe sounds we don’t 
like. While most people would agree that the sound coming out of a 
lawnmower or the larynx of a drill sergeant is pure noise, opinions 
on the latest LP release would vary. Whether the sound is judged to 
be pleasant or unpleasant depends on various factors including age, 
environment culture and advertising skills. We could say that music 
exists in the mind of the listener. Clearly, we need a simple 
definition for distinguishing noise from music without relying on 
vague subjective evaluations. In the science of acoustics, the term 
noise is used to describe sounds made up of completely random 
frequencies. It is convenient to subdivide noise into the following 
three frequency bands: 


Red noise — restricted to the lower end of the frequency spectrum. 
Pink noise — restricted to the medium frequency spectrum. 

White noise — unrestricted and covers the whole of the audio 
frequency spectrum. 


The noise generating facility on the Amstrad CPC464/664 machines 
will be used exclusively for sound effects, either to simulate 
explosions or as an important addition to the repertoire of a 
computerised synthesiser. 

Noise, as we have seen, is easy to define but music is not. To say 
it is non-random sound would be arguing in a circle. If a few 
inebriates slide on their backsides along the keyboard of a Steinway 
grand they are not producing noise in the acoustical sense because 
each one of the piano strings would be vibrating in accordance with 
a fixed and reproducible frequency pattern laid down by the piano 
tuner. Although it may not be noise in the acoustical sense, few 
listeners, other than some avant-garde weirdies, would describe it 
as musical. Music, especially good music, is difficult to define 
because it has no real part in nature’s scheme of things. Music is 
man made and has evolved slowly over many centuries and along 
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different paths. As an example of cultural differences, most of us 
can differentiate between ‘oriental’ and ‘western’ music, even 
though we may be hard pressed to describe exactly what the 
difference is. In what follows, we shall see that it is largely due toa 
difference in scales. 


Some musical terms 


Although some musical terms are explained in the User Instructions 
some readers may find the following additional treatment helpful. 
Pitch: number of complete sound vibrations per second. The unit is 
the hertz and represents a pitch of one vibration per second. (In 
physics, the term frequency is used instead of pitch but they are one 
and the same as far as the audio spectrum is concerned.) 

Period: time taken to complete one sound vibration. Period and pitch 
are related by the formula, 


Pitch=1/Period 


For example, a vibration with a pitch of 500 hertz would have a 
period of 1/500 second (2 milliseconds). The higher the pitch, the 
lower the period. It is worth noting that the formula is of the form 
Y=1/X, representing a rectangular hyperbola. Although this may 
interest only those with a mathematical background it is worth 
studying Figure 6.1 which shows the curve of the equation because 
it illustrates why the period of a note is not the best parameter to 
have chosen for the sound command. 


Period 


Fig 6.1 Pitch 


If say, 4 vibrations per second are added to a certain pitch, we 
can’t find the new period by just taking 4 away from the old period 
because, as the curve shows, it is a non-linear relationship. 
Musicians always feel more at home with pitch than with period. 
An orchestra tunes up to International A which is defined in terms 
of pitch as exactly 440 vibrations per second. If this is expressed in 


Some musical terms 


terms of period, we get a sickly looking number of 1/440=0.00227273 
seconds. When using the SOUND statement it will often be 
advantageous or, as far as musicians are concerned, mandatory to 
convert from period to pitch. 


The octave 

If one note has double the pitch (frequency) of another, the two 
notes are said to be an octave apart. A typical piano keyboard covers 
a range of seven and one quarter octaves. According to the table in 
appendix VII of the User Instructions, the sound generator on the 
Amstrad 464/664 machines has a range of eight octaves. However, 
the small internal speaker is quite unable to deal with such a 
frequency range so, unless a hi-fi amplifier is connected, it would be 
advisable to restrict the programmable range from octave —1 to 
octave 2. The octaves are numbered from the lowest to the highest, 
Op ey by Oi 268, 


Scale 


An octave can be divided up in various ways. As far as western 
music is concerned, an octave is divided into 12 parts known as 
semitones. A whole tone is therefore two semitones. There are twelve 
piano keys in each octave, each a semitone apart in pitch. If we start 
on middle C and play every note in succession, including the black 
ones, throughout the octave, we are playing a scale. Not a particu- 
larly interesting scale but nevertheless, a scale. It is called the 
chromatic scale. There are several, more or less, standardised types 
of scale, depending on which notes you play and which notes you 
miss out within an octave. The two most important in western 
music are the major and minor scales. Both of these scales use only 
eight of the 12 notes within an octave but they differ in the position 
of the semitones as follows: 


‘The major scale 


Semitones occur between the 3rd and 4th and between the 7th and 
8th notes of the octave. 


The scale can be considered a primitive form of tune, useful in 
singing classes for exercising the vocal chords or to improve finger 
dexterity on the keyboard. The note you start on is called the key. 
You can start on any note you like but it will only be a major scale if 
the semitones occur in the same relative positions as stated above. 
Because the notes played depend on the starting note, musicians 
use the following set of labels to identify each of the eight notes of 
the major scale, irrespective of the key: 
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First note=tonic (the key) 
Second note=supertonic 
Third note=mediant 
Fourth note=subdominant 
Fifth note=dominant 

Sixth note=submediant 
Seventh note=leading note 


If you play all the white notes from C up to the next C, you are 
playing a major scale in C. The notes will be C, D, E, F, G, A, B, C. 
This is why people who play by ‘ear’ often stick to the scale of C 
because they don’t have to remember where the semitones are - 
there are no black keys to fiddle around with. Melodies played on 
this scale are, in general, bright and cheerful — even if the words are 
gloomy! If some notes in a melody are foreign to the scale in use 
(quite a common practice) they are called ‘accidentals’. There are of 
course 12 different major scales, depending on the bottom note you 
start on but they will still all be major scales (they will all be the same 
tune) if they obey the rule above regarding the positions of the 
semitones. 


The minor scale 


Strictly, there are two types of minor scale, the melodic minor and 
the harmonic minor but we shall concentrate only on the melodic 
minor. 


Semitones occur between the 2nd and 3rd and between the 6th and 
7th notes of the scale. 


For example: the scale of C minor contains the notes C, D, D#, F, 
G, A, A#, C. Note that D to D# is the first semitone and A to A# 
is the second semitone. Melodies played in a minor key have a 
mysterious and slightly eerie ring about them. In the days of silent 
movies, the pianist played in a major key to signal the arrival of the 
hero and a minor key for the villain. 


Other scales 


We mentioned earlier that western and eastern music sound 
entirely different in character. One reason for the difference is the 
oriental love of the whole tone scale. That is to say, scales in which 
there are no semitones. In contrast, music of the Indian sub- 
continent often use scales using quarter tones. These melodies cannot 
be played on a normal piano keyboard but there seems to be no 
technical reason why they cannot be ‘played’ on the Amstrad. 


Chords 


There are three independent sound channels available, all capable 


Chords 


of sounding different notes at the same time which means that we 
can play chords. If the notes of a chord are spread out and played 
one after the other, instead of together, it is called an arpeggio. There 
is no space in a book of this kind to delve into the theory of chords 
and harmonic relationships. The best way to learn these is to get 
hold of a guitar, rather than a piano, tutor book. However, the 
following brief outline will help you to follow some of the sub- 
routines in this chapter: 


Intervals 

Two notes a certain distance apart in the scale are called intervals. 
Three note chords are called triads, some examples in the key of C 
Major being: 


Major third=C to E 

Minor third=C to D# 

Major fifth=C to G 

Minor seventh=C to A# 

Major triad=C and E and G 

Minor triad=C and D# and G 

Dominant seventh triad=C and G and A# 
Diminished seventh triad=C and D# and F# 
Augmented fifth triad=C and E and A# 


To play the same intervals or triads in, say, C# major, all the above 
notes must be played a semitone higher. Thus the major third 
would be C# and F and the minor seventh would be C# and B. 


Chord inversions 

Chords can be either in root position where the tonic is the lowest 
note or the order changed to produce inversions. For example, the 
first inversion of the major triad in C would be E and G and C in that 
order. 


Equal and just temperament scales 


String instruments such as the violin can play notes of any pitch 
within the compass of their range. Since the finger, used to shorten 
the effective string length, can be placed anywhere along the string 
it follows that, theoretically at least, an infinite number of possible 
notes are playable. Keyboard instruments cannot do this. The 
number of keys dictates the number of different notes and, what is 
more important, the number of notes within the range of an octave. 
This was a problem which occupied the minds of the great musi- 
cians of the past. The problem, deep rooted in harmonic theory, is 
concerned with the relationship between semitones and geometrical 
ratios. The pitch of each semitone must be separated from the next 
by a fixed geometric ratio. Because there are twelve semitones in a full 
chromatic scale, the ratio turns out to be 2”. The problem therefore 
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is how to make each key serve for two slightly different notes. For 
example, the black note immediately above C has to serve as C 
sharp and D flat. Similarly, F sharp and G flat have to share the 
same key and so on. In a perfect instrument, there would be 
separate keys for, say, C# and D flat because the geometric-ratio 
law demands that there will be a slight difference in pitch between 
them. The perfect scale, strictly observing the law, is known as the 
just-tempered scale. From earlier remarks, the violin or indeed any 
other similar stringed instrument could play the just tempered scale 
but keyboard instruments cannot. If one key, say, C major, is 
tuned exactly in accordance with just temperament, scales in other 
keys will sound rough. However, the problem was solved by an 
ingenious compromise. A keyboard instrument, if detuned slightly, 
in accordance with a fixed plan, can spread the inequalities over the 
octave. Johann Sebastian Bach composed his famous ‘48 Preludes 
and Fugues’ in order to prove that the new tuning method, known 
as ‘equal-tempering’ enabled melodies and chords to be played in any 
of the 12 keys without too serious a blow on the critical ears of his 
musical colleagues. 

The pitch numbers in Table 6.1 are in equal temperament. 
Western ears are, by now, so accustomed to equal temperament 
detuning, that a true just-tempered scale will sound a little ‘flat’. 

By now, some readers may be wondering if all this musical jargon 
is relevant. The answer is simple; if you are already a musician, you 
will be bored, perhaps even angry, at the above superficial treat- 
ment. However, if you are completely non-musical but like mathe- 
matical relationships, you will be able to write simple subroutines 
which play some impressive melodic or chord passages. They may 
not be up to Beethoven or Stravinsky standards but clockwork 
music is not the sole prerogative of Top of the Pops. 


Table 6.1 Relating musical notes to pitch numbers 

















Octave number 

—3 —2 -1 0 
C —36 —24 —12 0 
C# 35 23 11 1 
D —34 —22 —10 2 
D# —33 —21 -9 3 
E —32 —20 -8 4 
F —31 —19 —7 5 
F# —30 —18 -—6 6 
G —29 —17 —5 7 
G# —28 —16 —4 8 
A —27 —15 -3 9 
A# —26 —14 —2 10 
B —25 —13 —1 11 





Equal and just temperament scales 


Period and the SOUND command 


The table of frequencies and periods given in the appendix of the 
User instructions would be easier to manipulate if we could find a 
mathematical relationship between the pitch of a note and a simple 
integer of the form given in TABLE 6.1. 


The most important feature of this table is the fact that the 
numbers progress in the form of a simple count. As each note 
increases by one semitone, the corresponding pitch number is 


increased by 1. Figure 6.2 shows two octaves of a keyboard with 
pitch numbers taken from Table 6.1 
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Fig 6.2 Pitch numbers shown are from Table 6.1 


The linear relationship makes it easy to program ‘computer 
music’. Study the following examples: 


1 To raise or lower a note by an octave, add or subtract 12 
respectively. 

2 To raise or lower a note by a semitone, add or subtract 1 
respectively. 

3 To raise or lower a note by a full tone, add or subtract 2 
respectively. 

4 Adding 4 obtains the upper note of a major third and adding 3 
the upper note of a minor third. 


Using Table 6.1 
Before use can be made of the table we need a special user defined 
function: 


FNperiod(pitch)=ROUND(125000/(261.626* (2 (pitch/12)))) 


This function maps the pitch numbers shown in Table 6.1 exactly 
to the recommended period settings for the SOUND command. 
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However, we must first of all take a look at this command in its 
default state. That is to say, the form using only the first two 
parameters, channel number and period. To attempt to bring in the 
other parameters or to introduce the sound envelope at this stage 
would obscure essential features. The default form is as follows: 
SOUND channel status, tone period 

The default duration of the note is 1/5 second (20/100). 


Example 1 

Assume we wish to sound the note of D# in octave 0, using 
channel 1 by the normal method given in the User Instructions. We 
would turn to page 2 of appendix VII to discover that the period is 
given as 402. Plugging this value into the SOUND command gives: 


SOUND 1,402 


Example 2 

This time, we will use our special function and look up D# in 
octave 0 in Table 6.1. We note it is represented by the number 3 so 
the sound statement becomes: 


SOUND 1,FNperiod(3) 


At first sight, this seems more complicated than the original version 
but consider the advantages. For example, if we want the next 
highest note (E), we simply increase the number from 3 to 4 instead 
of going back again to page 2 of appendix VII to find the new period 
number (379). We can, of course, use variables instead of constants 
but the most important advantage is the ability to add an offset to 
the pitch number. For example, we can change the key of a melody 
or the position of a chord simply by changing the value of an offset 
or base number. The command would be of the form: 


SOUND 1,FNperiod(offset+N) 


Melodic sequences 


The pitch numbers of melodic sequences can be put into DATA 
statements and then read into SOUND commands. Normally, 
DATA statements are not put inside subroutines because of trouble 
with restoring the data pointer to the correct position. You will 
remember that a DATA line cannot be re-read unless the data 
pointer is first restored. However, Amstrad has been kind enough 
to supply a novel RESTORE statement which allows the data 
pointer to be reset to a given DATA line number. For example, we 
can write RESTORE 10100 which allows the DATA in line 10100 to 
be read again. This facility allows data statements to be packed 
inside a subroutine instead of being scattered globally. However, it 
depends very much on the general structure of a program whether 
we place them inside or outside. 


Period and the SOUND command 


Subroutine 6.1 Major scale subroutine 


10 REM EXAMPLE: ASCENDING MAJOR SCALES 

20 ’ 

30 DEF FNperiod (pitch) =ROUND (125000/ (261. 626% (2* (p 
itch/12)))) 

40 ' 

50 duration=10: of fset=0 

60 WHILE of fset<12 

70 GOSUB 10000 

80 of fset=offset+1 

90 WEND 

100 END 

110 ° 

9999 REM MAJOR SCALE SUBROUTINE 

10000 RESTORE 10050 

10010 FOR B=1i TO 16 

10020 READ N 

10030 SOUND 1,FNperiod (Ntoffset) ,duration 

10040 NEXT 

10050 DATA 0,2,4,5,7,9 
10060 DATA 12,11,9,7,5 
10070 RETURN 


1,1 


Objective: To play an ascending major scale in any key. 

Variable names: 

B=loop counter for reading in DATA 

N=basic pitch number 

offset=correction for keychange. If offset=0, the scale is in C major 
and starts on middle C 

duration=time note lasts in units of 1/50 seconds 

Preparation before calling with GOSUB: Assign values for offset and 
duration. 

Action required after RETURN: None. 

Dependent subroutines or functions: DEF FNperiod(pitch). 

How it works: The middle C major pitch numbers are picked up from 
DATA statements and, after conversion by FNpitch, become the 
period values for the SOUND command. 

Example calling program: This contains the pitch function, offset and 
duration values together with a loop causing twelve repeats, each a 
semitone higher in key. 

Suggested uses: It is a simple example but useful for experimenting 
with, and getting the feel of, the sound command. Try altering the 
starting values of offset and duration. The following changes to the 
DATA lines will convert the scales from major to melodic minor. 


10050 DATA 0,2,3,5,7,9,10,12 
10060 DATA 12,10,9,7,5,3,2,0 
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Music and noise 


Remember scales are merely standardised ‘tunes’ so alter the data 
statements if you want a different one, but, if you alter the total 
number of DATA items the loop counter limit in line 10010 must be 
changed accordingly. Always refer back to Table 6.1 for the pitch 
number because these are the numbers you will use for DATA. 


Subroutine 6.2 Chord subroutine 


10 REM EXAMPLE: PLAY A CHOSEN CHORD 

20 * 

30 DEF FNperiod (pitch) =ROUND (125000/ (261.626* (2% (p 
itch/12)))) 

40 ' 

SO WHILE 1<>2 

60 CLS 

70 PRINT"CHORD TYPES" 

80 PRINT:PRINT"(1) Major" 

90 PRINT" (2) Minor" 

100 PRINT"(3) Seventh" 

110 PRINT" (4) Diminished" 

120 PRINT"(5) Augmented":PRINT 

130 INPUT"Enter chord type number (1-5) "3chord 
140 INPUT"Enter base note number (-36 to 59)"sbase 
150 duration=200 

160 GOSUB 10000 

170 WEND 

180 END 

190 ° 

9999 REM CHORD SUBROUTINE 

10000 ON chord GOTO 10010, 10020, 10030, 10040, 10050 
10010 RESTORE 10100:GOTO 10060 

10020 RESTORE 10110:GOTO 10040 

10030 RESTORE 10120:GOTO 10060 

10040 RESTORE 10130:GOTO 10060 

10050 RESTORE 10140:GOTO 10060 

10060 READ first,second,third 

10070 SOUND 1,FNperiod (basetfirst) ,duration 
10080 SOUND 2,FNperiod (base+second) ,duration 
10090 SOUND 4,FNperiod (basetthird) ,duration 
10100 DATA 0,4,7 

10110 DATA 0,3,7 

10120 DATA 4,7,10 

10130 DATA 3,6,9 

10140 DATA 0,4,8 

10150 RETURN 


Objective: To sound any one of five standard triad chords in root 


Subroutine 6.2 Chord subroutine 


position and in any key. 

Variable names: 

chord=the number between 1 and 5 for selecting a chord 

first=1st note of the chord 

second=2nd note of the chord 

third=3rd note of the chord 

base=offset for determining the lowest note in the chord 
duration=the time a note lasts 

Action required before calling with GOSUB: The variable, chord, must 
be assigned a number between 1 and 5. 

The variable, base, must be assigned a number between —36 and 59. 
The variable, duration, must be assigned a poitive integer greater 
than zero. 

Action required after RETURN: None. 

Dependent subroutines or functions: DEF FNperiod(pitch). 

How it works: The pitch numbers for the chords are in groups of 
three DATA items within the subroutine. Depending on the chord 
parameter, one particular set of three is read into the variables first, 
second and third and then passed to the SOUND commands in the 
same order. The selection is achieved by the ON GOTO in line 
10000. The RESTORE commands are for resetting the data read 
pointer to the chosen DATA line. The variable, base, provides the 
offset for specifying the starting note of each chord. Note that the 
WHILE/WEND condition in line 50 is always true so the program 
runs for ever — until of course you press ESCAPE twice. 

Example calling program: After the customary DEF FNpitch function 
at line 30, the WHILE/WEND loop presents the menu of available 
chords and asks for the chord number and the base note. The 
duration is fixed at 200 (4 seconds) by line 160 but this can easily be 
altered. 

Suggested uses: A suitable calling program can arrange for the 
sounding of chord progressions. 

Notes: The DATA statements can be altered to provide other chords 
such as the added sixth and ninth or the same chords can be 
rearranged in their different inversions. 


Subroutine 6.3 Arpeggio subroutine 


10 REM EXAMPLE: PLAY A CHOSEN ARPEGGIO 

20 ° 

30 DEF FNperiad (pitch) =ROUND (125000/ (261. 626% (2% (p 
itch/12)))) 

40 ° 


SO WHILE 1<>2 
60 CLS 

PRINT"ARPEGGIO TYPES” 
80 PRINT:PRINT" (1) Major" 
90 PRINT"(2) Minor" 
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100 PRINT" (3) Seventh" 

110 PRINT"(4) Diminished" 

120 PRINT" (5) Augmented": PRINT 

130 INPUT"Enter chord type number (1-5)"3;chord 
140 INPUT"Enter base note number (-36 to 59)";0ffs 
et 

150 duration=10 

160 WHILE of fset<=48 

170 GOSUB 10000 

180 of fset=of fsett+12 

190 WEND 

200 WEND 

210 END 

220 ° 

9999 REM ARPEGGIO SUBROUTINE 

10000 ON chord GOTO 10010,10020, 10030, 10040, 10050 
10010 RESTORE 10110:GOTO 10060 

10020 RESTORE 10120:GOTO 10060 

10030 RESTORE 10130:GOTO 10060 

10040 RESTORE 10140:GOTO 10060 

10050 RESTORE 10150:GOTO 10060 

10060 READ notes 

10070 FOR A=i TO notes 

10080 READ N 

10090 SOUND 1,FNperiod (Ntoffset) ,duration 
10100 NEXT 


10110 DATA 3,0,4,7 
10120 DATA 3,0,3,7 
10130 DATA 4,0,4,7,10 
10140 DATA 4,0,3,46,9 
10150 DATA 3,0,4,8 


101460 RETURN 








Objective: To sound arpeggios based on any one of five standard 
chords. The number of notes in each arpeggio is selectable. 
Variable names: 

N=pitch number 

notes=number of notes in the arpeggio 

chord=a number between 1 and 5 for selecting a chord 
offset=number for determining the lowest note of the arpeggio 
A=loop counter 

duration=length of time the note lasts. 

Action required before calling with GOSUB: The variables duration, 
chord and offset must be passed. 

Action required after RETURN: None. 

Dependent subroutines or functions: DEF FNperiod(pitch). 

How it works: The first data item of each arpeggio is the number of 
notes which follow. This is read into the variable notes, used to set 


Subroutine 6.3 Arpeggio subroutine 


the loop counting limit. Apart from this difference, the structure is 
similar to that of subroutine 6.2. The speed at which the arpeggios 
are played can be varied over a wide range by altering the value of 
the variable duration. 

Example calling program: There are two WHILE/WEND loops. The 
outer ensures continuous operation and the inner produces 
arpeggios covering a range of four octaves. Note that line 180 
increases the offset by 12 (one octave). 

Suggested uses: Apart from experimenting with a range of arpeggios, 
it can provide pleasant jingles for accompanying games. 


Subroutine 6.4 Tune subroutine 


10 REM EXAMPLE: PLAY A SIMPLE TUNE 
20 ’ 

30 DEF FNperiod (pitch) =ROUND (125000/ (261. 626% (2* (p 
itch/12)))) 

40 ’ 

SO WHILE 1<>2 

60 GOSUB 10000 

70 WEND 

80 END 

90 ° 

9999 REM TUNE SUBROUTINE 

10000 RESTORE 10080 

10010 duration=30 

10020 FOR B=1 TO 44 

10030 READ N 

10040 SOUND 1,FNperiod(N) ,duration 
10050 SOUND 2,FNperiod(N+12) ,duration 
10060 SOUND 4,FNperiod (N+24) ,duration 
10070 NEXT 

10080 DATA 0,-5,0,2,4,0,7,4 

10090 DATA 0,-3,0,2,0,-3,-7,0 


10100 DATA -2,-7,2,0, 23, -7,2,0 
10110 DATA -1,-5,2,0,-1,-5,-3,-1 
10120 DATA 0,12,0,12,-5,7,-5,7 
10130 DATA -3,9,-3,9,—-7 955-755 
10140 DATA -2,10,-2,10,-7,5,-7,5 
10150 DATA -1,11,-1,11,-5,7,-5,7 
10160 RETURN 





Objective: A simple tune played in three voice octaves, completely 
self-contained in a subroutine, using the minimum amount of 
programming effort. The three octaves give a satisfying quality to 
the sound without bothering with the complexities of the EN- 
VELOPE command. This is because the raw sound output is 
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approximately square wave in form and, therefore, rich in odd 
harmonics. 

Variable names: 

N=pitch number 

duration=length of notes 

B=loop counter 

Action required before calling with GOSUB: The variable, duration, 
must be assigned a value. 

Dependent subroutines or functions: DEF FNperiod(pitch). 

How it works: The pitch numbers forming the tune appear as 64 
DATA items. They are read into the three sound channels by the 
FOR/NEXT loop. Channels 2 and 4 have offsets of 12 and 24 
respectively to produce the octave shifts. 

Example calling program: The WHILE/WEND condition ensures con- 
tinuous operation. The duration can be changed at will by altering 
line 10010. 

Suggested uses: Ideal as a signature tune to mark the start of a game 
etc. The actual melody, of course, can be changed by the DATA 
items. If your new tune requires more (or less) data items, the loop 
counter limit must be changed accordingly in line 10020. 


Subroutines 6.5 Standard boogie/blues sequence 
























10 REM EXAMPLE: 12 BAR BOOGIE MUSIC 
20° 

30 DEF FNperiod (pitch) =ROUND (125000/ (261. 626% (2*(p 
itch/12)))) 

40 ' 

5Oo CLS 

60 INPUT"Give base pitch number (-36 to 59)"sbase% 


70 INPUT"Enter tempo (1-15)";tempoZ% 
80 INPUT"Play how many times";playsZ% 
90 duration=8 

100 GOSUB 140 

110 END 

120 ° 

130 REM PLAY STANDARD BOOGIE SEQUENCE 
140 KZ=O0:WHILE KZ<plays~z 

150 of fset=0:repeat=4:GOSUB 2460 

160 of fset=5:repeat=2:GOSUB 260 

170 of fset=0:GOSUB 240 

180 of fset=-S:repeat=1:GOSUB 260 

190 of fset=5:GOSUB 240 

200 of fset=O0:repeat=2:GOSUB 2460 

210 KZ=KZ+1 

WEND 





Subroutines 6.5 Standard boogie/blues sequence 


RETURN 


REM REPEAT RIFF SUBROUTINE 

FOR A=1 TO repeat 

RESTORE 330 

FOR B=1 TO 8 

READ NZ 

SOUND 1,FNperiod (baseZt+toffset+N%) ,duration*tem 


NEXT 
NEXT 

DATA 0,12,4,556573-597 
RETURN 


Objective: Plays any repetitive riff based on the standard 12 bar blues 
chord foundation. The example riff is an eight-note boogie pattern. 
Variable names: 

N%=pitch number 

B=loop counter for DATA items 

A=loop counter for repeating phrases 

base% =foundation pitch 

K%=loop counter for number of complete plays 

tempo% =sets playing speed 

plays% =number of times the complete sequence is to be played 
offset=correction for changing the pitch for each phrase of the blues 
duration=length of each note 

Action required before calling with GOSUB: The variables base%, 
tempo%, plays% and duration must be assigned. 

Dependent subroutines or functions: DEF FNperiod(pitch). 

How it works: There are two subroutines: The Riff subroutine is 
responsible for sounding the 8 note melodic boogie pattern. It is 
called up by the first subroutine which handles the changes in 
harmony and the number of times each blues phrase has to be 
repeated. 

Example calling program: This allows the operator to choose the base 
pitch number, tempo and how many times the sequence is to be 
played. The duration of each note is set to 8 in line 90 but can be 
altered as required. 

Suggested uses: As a rhythmic accompaniment to a scene in a game or 
as one component of a complex musical arrangement. The DATA 
statements can be changed to cover different riffs or melodic 
patterns. 


Sound synthesising 


Up to now, we have dealt with simple methods of utilising the three 
sound channels, using fixed offsets. This is ideal if chord sequences 
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are required but when exploring the world of harmony and counter- 
point these methods fall short. We need to supply each channel 
with its own exclusive data. 


Three independent channels 

Most simple music scores can be broken down into a bass pattern, a 
middle section and a melody. These may be played at timings not 
necessarily in unison. For this reason, the Amstrad 464/664 de- 
signers have given us three channels, each with their own separate 
interrupts. When constructing sound synthesiser programs, it is 
conventional to place the musical data into DATA statements. This 
makes the task of editing and correcting particularly easy, especially 
if the data for all three channels appears at the foot of the program. 


Collecting the DATA statements 

In earlier examples we used READ/DATA commands to pick up the 
data and place them immediately into the chosen sound queue. 
Execution of the program would thus be halted automatically by the 
operating system until a place in the sound channel queue was 
available. In a system which employs more than one channel 
independently, this method is not practical because data would be 
needed from more than one list (one for each channel). It would be 
necessary to consult lists in rotation and be able to reset the data 
pointer to the last used data element in each list. Since a RESTORE 
command defaults to the start of the data list, the only possible way 
to restore the data pointer to where it left off would be to READ 
through the list again until the point is reached where we left off. 
This is possible, but the execution time would severely limit the 
speed at which a tune could be played. Even so, we might miss a 
note intended for another channel while waiting to insert data into a 
particular queue. 

Fortunately, there is a simple solution. All we need to do is to 
collect all the data from the lists into arrays before we start. We can 
switch between arrays and set the index to the sound data im- 
mediately to where we left off. In addition, the use of sound 
interrupt techniques will ensure that the above problems will not 
occur in practice. Moreover, the relevant sound queues can be fed as 
quickly as the fastest a tune can be deciphered by the ear. 

At the same time as the data is collected into arrays it is 
convenient to process it into the final form acceptable to the SOUND 
command. This will involve adjustments for tempo and the usual 
pitch to period transformations. 


Feeding the SOUND queues 
The simplest way to feed the sound queues for each channel is to 
use the ON SQ GOSUB interrupt commands. In view of the power 
and flexibility of queueing and interrupts, it is worth digressing a 
little to reinforce the details. 

The sound queue for each channel is capable of storing the data of 
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up to five complete SOUND statements of which only the first is 
currently active. When the active sound has finished, the queue 
moves up (like a queue at a bank) and a space becomes available at 
the other end. At this time it is possible to insert another package of 
data. Sound queueing has many advantages, the most important 
being that slight delays introduced in program loops will not affect 
the overall timing of a tune. 


Sound interrupts 
Sound generation is a relatively time-consuming process compared 
with the speed of the computer itself. While the sound generator 
chip is engaged producing the desired sound from a particular 
channel, the computer can be busy processing elsewhere. So long as 
the computer finds time to top up the queue now and again that is 
all that matters. This is where sound interrupts come in. The sound 
queue may be fed whenever a space becomes available. 

The AMSTRAD 464/664 version of BASIC provides each of its 
three sound queues with an independent interrupt capability by 
means of the following commands: 


ON SQ(1) GOSUB <line number> 


This causes an interrupt when a space becomes available in the 
Channel A queue. 


ON SQ(2) GOSUB <line number> 


This causes an interrupt when a space becomes available in the 
Channel B queue. 


ON SQ(4) GOSUB <line number> 


This causes an interrupt when a space becomes available in the 
Channel C queue. 

There is nothing sinister in the concept of sound interrupts. They 
offer a way of claiming the immediate and undivided attention of 
the computer. The following provides a typical example of the train 
of events: 


1 The computer is busy performing some task or perhaps idling its 
time away within a WHILE/WEND loop. 

2 An interrupt is generated when the condition specified by an 
ON SQ(1) GOSUB 1000 command is true. This occurs when a space 
is available in the sound queue of Channel A. 

3 The computer stores the data it needs in order to return to where 
it left off. (This is done automatically by BASIC). 

4 The computer’s attention is diverted to the specified subroutine 
at line number 1000. This subroutine tops up the queue with more 
sound data, via the use of the SOUND command. If the subroutine 
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contains a SOUND or SQ command further interrupts will be 
disabled. Therefore to re-enable interrupts, the last statement before 
RETURN must be a further ON SQ(1) GOSUB 1000. 

5 On encountering a return command the computer carries on 
with its original task. 
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10 REM PROGRAM: 3 CHANNEL SYNTHESISER 
20 ’ 

30 DEF FNperiod (pitch) =ROUND (125000/ (261. 626* (2% (p 
itch/12)))) 

40 ’ 

SO DIM note~%(2,4600) 

60 #lagAZ=0: fl agB%Z=0: £1 agC%Z=0 

7O p%Z=1:q%=1:r%=1 

80 CLS 

90 INPUT"Enter tempo (1-15)"3; tempo 
100 IF tempo<i OR tempo>15 THEN 90 
110 INPUT"Enter base note number (-36 to 59)";base 
% 

120 IF baseZ%Z<-36 OR base%~>59 THEN 110 
130 GOSUB 420 

140 chanZ=0:GOSUB 310:sizeAZ=NZ% 

150 chanZ=1:GOSUB 310:sizeBZ=N% 

160 chanZ=2:GOSUB 310:sizeC%Z=NZ% 

170 GOSUB 230 

180 WHILE flagAZ+flagB%Z+flagC%Z<3 

190 WEND 

200 END 

210 

220 REM PRIME SOUND QUEUES 

230 SOUND &C7,0,200 

240 RELEASE 7 

250 ON SQ(1) GOSUB 440 

260 ON SQ(2) GOSUB 500 

270 ON SQ(4) GOSUB 540 

280 RETURN 

290 ‘ 

300 REM Place CHANNEL data into array 
310 NZ=1:pitch$="" 

320 WHILE pitch$<>"end" 

330 READ pitch$ 

340 IF pitch$="end" THEN 400 

350 note% (chanZ,NZ) =FNper iod (base%+VAL (pitch$) ) 
360 NZ=NZ+1 

370 READ durations 
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380 noteZ%(chanZ,NZ) =INT (tempo*VAL (duration) ) 

390 NZ=NZ+1 

400 WEND 

410 RETURN 

420 ° 

430 REM Insert QUEUE Channel A 

440 SOUND 1,noteZ%(0,pZ) ,noteZ(0,pZ%Z+1) ,0,1,1 

450 p%=p%+2 

460 IF p%<sizeAZ THEN ON S@Q(1) GOSUB 440 ELSE flag 
AZ=1 

470 RETURN 

480 ‘ 

490 REM Insert QUEUE Channel B 

500 SOUND 2,noteZ(1,q%) ,noteZ(1,q%+1) ,0,2 

510 qZ=q4t+2 

520 IF q%<sizeB%Z THEN ON SQ@(2) GOSUB 500 ELSE flag 
BZz=1 

530 RETURN 

540 ' 

550 REM Insert QUEUE Channel C 

560 SOUND 4,note%(2,r%) ,note%Z(2,r%+1) ,0,3 

570 r%Z=r%Z+2 

580 IF r%<sizeC%Z THEN ON SQ(4) GOSUB 560 ELSE flag 
Cz=1 

590 RETURN 


600 
610 REM OF ENVELOPES USED 


620 ENV 71,0,8,15,-1,4 

630 ENV 79,16,15,-1,2 

640 ENV 0,4,15,-1,6 

650 ENT gr lgl y45251,525-1,1 

660 RETURN 

4670 ° 

680 REM Channel A data 

690 DATA 0,8, 12,8, 4,8, 5,8, 6,8, 7,8, -5,8, 7,8 
700 DATA end 

710 ° 

720 REM Channel 

730 DATA 22,16, 

740 DATA end 

750 ’ 

760 REM Channel 

770 DATA 15,16, 22,16, 24,16 
780 DATA end 





Program 6.1 is the minimum requirement for a full three channel 
sound synthesiser, employing both three section ASR amplitude 
envelopes (Attack Sustain Release) and vibrato pitch envelopes. It is 
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still a powerful routine, making full use of facilities offered by 
Amstrad’s impressive version of BASIC. 


How to use the program 

After typing in and testing the routine with the data provided you 
should hear a short but rather pleasing jingle, reminiscent of a radio 
station call sign. If you have experimented with single channel 
sounds then you will appreciate the difference in overall complexity 
of the multichannel sound. 

Initially, an overall system must be developed for coding a tune 
by means of DATA statements. The following decisions must be 
made: 

1 The format of the data. 

2 The maximum resolution the system is to cope with. (The 
smallest duration a note is likely to have). 

3 Periods of silence need to be catered for. (Rests are as important 
in music as the notes themselves). 

4 How to enter repeat passages which often occur in simple tunes. 
5 A method of disabling unrequired channels. 

6 A method of terminating each data list properly so that the 
program can detect the end-of-DATA statements in each specific 
channel. 

7 Amethod of entering the envelope data into the commands ENT 
and/or ENV. 


The format of the data 

Excluding subleties, such as dynamic range (the relative volume of 
notes), each note has two basic qualities, pitch and duration. To 
simplify the entry of DATA we shall leave fixed amplitude and pitch 
envelopes to take care of the character and timbre of the notes for 
each voice. To specify each note in the appropriate channel DATA 
statements we need: 


1 The pitch number 
2 The relative duration 


The pitch number, of course, is obtained by using our function 
FNperiod(pitch) in conjunction with Table 6.1. This alleviates the 
complication of specifying individual octaves because each note, in 
the full 8 octaves, has been given a unique sequential number. 


Relative duration of the note 

The longest duration note likely to be encountered in music is the 
breve, while the shortest duration note will be the demi-semi quaver. 
Thefore to specify the duration of any note encountered in music we 
need relative durations for each. Figure 6.3 shows a table of 
durations, the highest resolution being the demi-semi quaver with a 
relative duration of 1. Each note in the group then doubles the 
duration of the note through the range until finally the breve is 
encountered with a relative duration of 64. The incremental series 
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for duration is thus based on a simple doubling system starting with 
one, and therefore easy to remember. Dot notation is often en- 
countered in music, taking the form of a note, say a crochet, 
followed by a dot. This signifies that the duration is increased by 
half the note value. In our system, the dotted crotchet’s relative 
duration is 8+4=12. 
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Fig 6.3 


If we base all tunes on these relative durations we can multiply by 
some fixed variable to adjust the overall tempo. It works out, 
however, that this fixed tempo variable will always be greater than 
one, since any tune played at relative duration speed without some 
multiplication would not be recognisable. 


Periods of silence 

In order to produce a period of silence all that is needed is to specify 
a tone period in the SOUND statement of zero. However, there is 
one complication with our system. The function FNperiod(pitch) 
translates a pitch number to the correct period setting for inclusion 
in the SOUND statement. Therefore we need a pitch number that 
always evaluates through the function to a period of zero. One such 
value is 144. Figure 6.3 shows this in an easily digestible form. It is 
possible to have rests equal to any note duration by using 144 as 
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the pitch number and the relative duration as given in Figure 6.3. 
For example the data pair 144, 64 will ensure a rest equal to the 
duration of one breve. Of course, longer periods of silence can be 
programmed by using relative durations greater than 64. 


Repeat passages 

Repeat passages could not be easier. Simply use the cursor copy 
keys to duplicate the required repeated data into another DATA 
statement. There is plenty of memory available to store and play the 
vast majority of tunes. 


Unrequired channels 
Unrequired channels can be disabled by placing a single rest of any 
duration in any unused channel DATA list. 


Terminating data lists 
Data lists can be signalled by a word such as ‘end’ or ‘finish’. 


Entering the envelope data 

Envelope data can be entered into a list, contained in a subroutine, 
at the foot of the program. Envelopes are well described in the User 
Instructions (Chapter Six) but can be tricky to set up in practice. To 
simulate most musical instruments all that is required is a three 
section ASR amplitude envelope. However, a more faithful syn- 
thesis can be achieved by what is known as a four section ADSR 
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(Attack, Decay, Sustain, Release) amplitude envelope. However, it 
is doubtful if the small speaker of the Amstrad machines, or in fact 
any other current micro, will be capable of resolving the subtle 
difference unless connected to a hi-fi amplifier. (Please do not 
attempt to do this yourself unless you are well qualified in practical 
electronics. The results could be disastrous both to yourself and the 
computer!) Figure 6.4 shows the two common types of amplitude 
envelope used in sound synthesis. The diagram shows idealised 
smooth curves but, in practice, this is synthesised in small steps as 
shown in the User Instruction manual. As a useful rule of thumb, 
use a short attack time and a long release time to simulate percussion 
instruments such as a piano and a long attack time and a shorter 
release time for bowed string instruments. 


Program breakdown 


Line 30 This is our familiar pitch number-to-period function. 

Line 50 Dimensions the main data array. This is a 3 by 600 
rectangular array (remember that zero is a positive number in 
computing). 

Lines 60 to 70 initialise a finish flag and data array pointer for each 
channel. 

Lines 80 to 120 cater for responses from the keyboard. The user is 
first asked for the tempo in the range 1-15. This does not have to be 
an integer so fine adjustments to tempo can be performed. 

Secondly, the base note number is entered. This determines the 
key in which the tune is to be played. It is recommended that all 
tunes be programmed in or around octave zero and any adjust- 
ments to the key performed by setting the base note number at this 
stage. 

ne 130 calls on the List of envelopes subroutine. 

Lines 140 to 160 pick up the items from the DATA statements and 
place them in a rectangular array. This is done by 3 calls to the 
subroutine at line 310. The chan% index variable is set to zero for 
channel A, 1 for channel B and 2 for channel C. Thus the rectangular 
array can be thought of as three separate arrays. The variables 
sizeA%, sizeB% and sizeC% correspond to the number of notes in 
channels A, B and C respectively. 

Line 170 calls the subroutine at line 230 for priming the sound 
queues and to set the interrupts. Lines 180 to 190 form a time- 
wasting loop, inside which the computer can perform other tasks if 
required. In this particular case the time is just wasted. The loop will 
continue to execute until all the flags are set to one, indicating that 
all array sections have deposited data into their corresponding 
sound queues. 

Line 230 specifies a period of silence (tone period zero) for a 
duration of two seconds to each of the three channel queues and 
holds them. This is achieved by setting bits 7, 2, 1, and 0 of the 
channel status parameter to binary 1. 
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Line 240 releases all three sound queues simultaneously by 
setting bits 0, 1 and 2 to binary 1 to ensure that all three channels are 
properly synchronised. 

Lines 250 to 270 set interrupts to occur on all three channels. 
While the initial dummy synchronisation sound is being executed 
by the sound chip, the computer quickly fills the sound queues of 
each channel ready to start playing the tune. This is performed by 
interrupt calls to the subroutines at lines 440, 500 and 560 until the 
queues are filled. 

Lines 310 to 400 fill the data arrays. The channel A data is placed 
into the note%(0,N%) array section. When the word ‘end’ is 
encountered, the variable N% is reset to 1 and the note%(1,N%) 
array section starts to fill from the channel B data. Finally, the 
note%(2,N%) array section is loaded with the channel C data by a 
similar process. The array sections are loaded with sequential data, 
so note%(0,1) will be a pitch number and note%(0,2) a relative 
duration value and so on. At the same time as this process is 
performed, the items from the DATA statements are translated to 
the final form required for the sound statement. The pitch numbers 
are converted to period settings. The relative durations are con- 
verted by multiplying by tempo to the actual duration values. The 
integer function is used on the result in case tempo is entered as a 
decimal value. 

Lines 560 to 590 are the interrupt subroutine for channel A. An 
interrupt is generated when a space becomes available in the 
channel A sound queue. The SOUND command is constructed from 
the two successive array elements of note%(0,p%). The variable p% 
is then increased by 2, ready to access the next data pair for 
channel A. If the variable p% is less than size A% then the array 
section has not yet deposited all its data into the sound queue. 
Therefore the interrupt must be set ready for the next time a space 
becomes available in the queue. Remember that a sound command 
disables the ON SQ GOSUB interrupt, so it must be reset if required 
again. When p%>=size A% then flagA% is set, signalling ex- 
haustion of data. 

Lines 500 to 530 form the interrupt subroutine for feeding the 
channel B queue and is similar in form to channel A. 

Lines 560 to 590 is the ON SQ interrupt subroutine for feeding the 
channel C queue. 

Lines 620 to 660 lay down the list of envelopes, using the syntax 
given in the User Instruction manual. 

Lines 680 to 780 contain the sequence of DATA statements for 
each channel, arranged in pairs corresponding to pitch number and 
relative duration. Remember to terminate each channel's data list by 
the word ‘end’ or the program will not work as expected. 


Epilogue 
Program 6.1 shows the essential details of a straightforward method 
of using the three sound channels independently. There are of 
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course many other ways of accomplishing the same objective but 
beware of going over the top. Too many options or combinations 
can make a program difficult to use. Always plan your program on 
paper with an objective in mind, however simple. It always pays 
dividends in the end. Creating a program at the keyboard often 
works but the habit can lead to haphazard data structures, poor 
efficiency and bad structure. This can of course happen even if 
planned out on paper, but at least the likelihood is reduced. 


Summary 


1 Noise is sound consisting of random frequencies. 

2 Pitch is number of sound vibrations per second. (Synonymous 
with frequency in physics.) 

3 Period is time for one vibration. 

4 Period and pitch are non-linearly related. 

5 An octave is a musical interval formed by a note having double 
the pitch of another note. 

6 Western music divides the octave into 12 notes called semitones. 
7 Ascale is a certain standardised series of notes within an octave. 
8 Both major and minor scales have eight notes in the octave but 
they differ in the position of semitones. 

9 An accidental is a note foreign to the scale in use. 

10. Achord is the sound produced by striking more than one note 
at a time. 

11 An arpeggio is a series of separate notes based on a chord. 

12 Inversions are chords played other than in root position. 

13 The equal-tempered scale relies on slight detuning of certain 
intervals. 

14 The pitch numbers forming a melody may be placed in DATA 
statements. 

15 The sound queue for each channel can hold up to five SOUND 
commands. 
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Introduction 


Although frequent reference is made to cassette and tape files in this 
chapter, all the input and output filing commands on stream #9 are 
still valid for disc use. When a disc is connected, such as in the 
CPC664, the system automatically defaults to disc rather than tape. 
Needless to say, all program listings have been tested on both the 
CPC464 and the CPC664. However, for standard CPC464 users, it is 
often an advantage to permanently allocate the cassette buffer areas 
as described in Chapter 1. This will increase the file loading and 
saving speeds since the file arrays will not have to be moved prior to 
the normal dynamic allocation of the tape buffers. 

This chapter will contain a full listing of a practical general 
purpose filing program. It is written for cassette use although only 
one or two of the lines would need modifying to suit disc operation. 
It is built from a set of subroutines, but these will be described from 
within the program instead of being presented separately. Storing 
and retrieving information is a natural task for a computer. A 
relatively enormous amount of information can be stored and, more 
importantly, particular items retrieved with far greater speed than is 
possible with traditional office files or card index systems. However, 
the accuracy of the information held on a computer file is still 
dependent on a human operator so the design of a filing system 
should always take into account the possibility of false entries and 
ensure that certain types of error are easily detected at input level 
and equally easily corrected. Programs which organise and pro- 
cess information are little more than tools so the practical value of a 
computerised filing system depends largely on the manner in which 
file information is classified. Computer programs allow the user 
some freedom in the way the file information is structured but it will 
always be up to the user to decide how that freedom is exercised. 
For example, the name given to each heading in the file, the material 
to be included, the number of different headings, the space allowed 
for each item of text under a heading, the abbreviations, the 
particular heading which is to be considered more important than 
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other headings — all these points and many others must be con- 
sidered before deciding on the initial file layout. It could be irritating 
to discover that a file, having been in use for some time, should 
have had one or more extra fields. Scrapping it and re-entering the 
data in a more suitable format could be the only way out. It is 
possible to prevent such a mishap occurring by allowing for spare 
fields when creating the file or to arrange the program to allow extra 
fields to be added at any time. Indeed, a file handling program 
could be designed to cater for any human frailty but it could grow 
unwieldy and eat deeply into available RAM space. 


User-friendliness 


One aspect of user-friendliness is the incorporation of ‘ Are you 
sure?’ messages sent to the screen in circumstances where the 
wrong decision on the part of the operator could jeopardise the 
integrity of the file. For example, the original question might have 
been ‘Do you want this record to be deleted. Answer Y/N’. If the 
operator, in a moment of carelessness, answers with Y (but in- 
tended N) a valuable record could be destroyed. This could be 
catastrophic so a further message, ‘Are you sure?’, would contribute 
to user-friendliness. 

Simple and unequivocal screen messages, perhaps with some 
added colour for emphasis, are also important aids to friendliness. 
The Amstrad CPC464/664 offers a wide colour range and, used with 
discretion, can add force to the presentation of screen information. 

User-friendliness, if taken to excess, can be self-defeating. It takes 
some time for a novice operator to make full use of every option in a 
filing program. In the first few weeks of use, a high degree of user- 
friendliness may be appreciated but the same novice will eventually 
becomes skilled, and consequently irritated, if too many warnings 
have to be answered: with ‘Y/N’ entries. Besides, user-friendliness 
does eat into memory and, in a RAM-resident program, memory 
space is gold. The filing program in this chapter is therefore 
moderately friendly. 


Data files 


The words ‘data’ and ‘file’ in computer language are used with a 
variety of meanings. For example, it is customary in user handbooks 
to call everything a file which is stored on tape or disc — even 
programs! In this chapter, a data file will have the following 
meaning: 


A data file is a collection of related data held on tape or disc and 
accessed by a program in RAM 
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For example, one file could contain information on politicians and 
civil servants, another on lepidoptera. Perhaps the most popular 
type of domestic file is a list of names, addresses, marital status and 
telephone numbers. 

As explained earlier, the choice of material to go into one file is a 
human decision. Whether or not the contents of the file are indeed 
‘related’ must depend on the judgement of the person setting up the 
file. 


Record 

A file contains information which is in some way related, and 
containing a number of individual ‘records’. For example, a file on 
customers’ names and addresses will contain separate records for 
each customer. We can therefore define a record as follows: 


A record contains information on one particular entity. 


For example, a file on military aircraft would contain a number of 
records, one for each model. 


Field 
A ‘field’ is to a record as a record is to a file, so the following 
definition is appropriate: 


A field is a subdivision of a record and represents one aspect of the 
total information in a record. 


As an example, the file on military aircraft could reserve one field for 
the type, another the fire power, another the range in nautical miles 
and so on. 


Field headings: 
All fields must have a heading in order for the data to have meaning. 


Field width 

The number of characters allowed in a field is called the field width. 
There will be a theoretical upper limit of 254 characters per field but, 
as we shall see later, it is highly unlikely that such extravagance can 
be tolerated with cassette tape files so we shall most likely end up 
with a field width nearer to 20 characters. 


The key field 

Although all fields of a record will contain important information, 
one of them, the key field, will enjoy higher status. It is called the key 
field because it uniquely identifies the record. Searching for a record 
by quoting the key field is efficient and achieves fast results. We 
must be careful that our key field is indeed unique. A problem could 
arise in some files, particularly where the key field is a person’s 
name. It is quite possible for more than one Scargill A to be present 
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in the same file so, where this happens, an extra identifier could be 
added, such as Scargill A2. The safe way, particularly in larger files, 
is to use a code identifier as the key field (perhaps ten or more 
characters) rather than a person’s name. 

Figure 7.1 illustrates the relationship between the field, the record 
and the file. 


File 
Record 1 


Record 2 Example record 


Record 3 





Fields 





Fig 7.1 
RAM based and store based files 


Various factors can influence the information grouped under one 
file, including the physical limitations imposed by RAM size or the 
type of storage system. These limitations will depend to a large 
extent on the methods employed in the program. There are several 
recognised methods of organising files but it is sufficient to distin- 
guish two broad divisions: 


RAM-based sequential files 

The entire file must be loaded from store into RAM before indi- 
vidual records can be accessed. Unfortunately, this is the only 
practical class of file for cassette tape storage. 


Store-based files 

The file remains in store and only the chosen record, or in some 
cases a few records, are loaded into RAM as required. These include 
indexed files and random access files. 


File size 
As mentioned above, practical cassette-based filing systems must be 
RAM based which clearly limits the size of a file. The following 
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equation is useful for estimating the RAM space in bytes: 


Number of bytes=Field-width x number of fields x number of 
records 


This equation should act as a sobering influence when planning the 
file layout. 

With store based files, the amount of available RAM is less 
important because the limiting factor on file length is the amount of 
disc storage available. However, in cases where the length of the 
files are well within the capacity of RAM, there is a distinct 
advantage in using them. Once a complete file is loaded into RAM, 
essential processes, such as record searching and sorting, are 
completed at RAM speed. Sorting records into some kind of order is 
the one process at which RAM based files excel. 


File splitting and merging 

The number of records in a file heading can eventually become too 
large to fit into RAM. This can be overcome by including an option 
for splitting a single file into one or more subfiles. For example, if 
the key field is the name of something, it may be advisable to split 
the file into names beginning with A to J, another beginning with K 
to R and another with S to Z. Conversely, it might be useful to have 
a facility for merging two or more smaller files into one. 


Storing and retrieving data files 
There are special commands for dealing with data files. We can’t 
simply LOAD and SAVE like we do with programs. 


Opening a data file for output 

At the point in a program where data is to be stored on tape, it is 
necessary to open a tape file by using the following OPENOUT 
statement, 


OPENOUT “FILENAME” 


The file name can be literal, such as OPENOUT “RIVERS” or a 
string variable which has been previously assigned. No more than 
16 characters are allowed for a file name. 


Using PRINT #9 
Once the file has been opened for output, the data can be written to 
tape by a special print statement having the format, 


PRINT #9,variable list 
The ‘#9’ informs the system that the ‘printing’ is to be carried out 


on output stream ‘9’, which is the cassette tape unit, rather than on 
the monitor screen by default. The term ‘variable list’ above means 
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one or more variables, separated by commas such as 
PRINT #9, A%,B% 


When a complete data file, normally held in a two-dimensional 
array, is to be printed to tape, there is first a need to store certain 
leading particulars of the file. For example, when the file is loaded, 
the program which loads it will have no information as to the length 
of the file or the number of fields in each record. These details must 
be obtained from the data tape before loop parameters can be set up 
for reading back the file. 

The baud rate at which the data is sent to tape will be the default 
speed of 1000. However, if you wish to send it along at 2000 baud, 
then follow the OPENOUT line with SPEED WRITE 1. 


Using WRITE #9 

The command WRITE #9 is similar in most respects to PRINT #9 
except it is less versatile. The essential difference is that when using 
WRITE #9, commas are used to separate variable values and all 
strings are enclosed by double quotes. This is perhaps the favoured 
method of writing to tape since commas etc can be included in 
strings without upsetting the system when the string is read back 
from tape. 


Closing a file 

After the data has been output to tape it is important to CLOSEOUT 
the file when you have finished with it because there may still be 
data left in the cassette buffer area of RAM. The act of closing the file 
flushes out any data that remains in the buffer and writes it to tape. 


Opening a data file for input 
To retrieve a data file from tape, it is again necessary to open a file, 
but this time, the keyword is OPENIN followed by the file name: 


OPENIN“filename” or OPENIN <string variable> 


Using INPUT #9 
Normally, the INPUT statement receives data from the default input 
peripheral, which is the keyboard. To input data from tape, the 
equivalent form is 


INPUT #9, <variable list> 


For example, 
INPUT #9,A%_,B% 


After all data has been retrieved from tape, the input file should be 
closed in the usual way with CLOSEIN “filename’”’ or CLOSEIN 
string variable. 
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Before running a program which calls up a data file from tape, 
ensure you have the relevant tape in place and rewound. 
Complete RAM-based serial filing system 


We now describe the operation and description of a complete, and 
we hope useful, filing program. 


Program 7.1 









10 REM RAM RESIDENT FILING SYSTEM 
20 REM FOR USE WITH CASSETTE OR DISC 

30 REM ON AMSTRAD CPC464 & CPC4&64 

40 ' 

SO MODE 1 

60 INK 0,0: INK 2,18 

7O mainsize%=0 

80 GOSUB 3140 

90 LOCATE 1,7 

100 PRINT"PRIMARY MENU" 

110 LOCATE 1,12 

120 PRINT"(1) Create new file" 

130 PRINT"(2) Load existing file" 

140 PRINT"(3) Exit program" 

150 LOCATE 1,21 

160 CHOICE$="123":GOSUB 460 

170 CLS 

180 ON SEL% GOSUB 550,710,410 

190 GOSUB 3140 

200 LOCATE 1,6 

210 PRINT"MAIN FILE MENU" 

220 LOCATE 1,9 

230 PRINT"(A) Save file" 

240 PRINT" (B) Display file" 

250 PRINT"(C) Add records" 

260 PRINT"(D) Modify any field” 

270 PRINT"(E) Delete record" 

280 PRINT"(F) Sort by any field" 

290 PRINT"(G) Create sub-file (Search any field)" 
300 PRINT"(H) Print File” 

310 PRINT"(I) Display single record" 
320 PRINT"(J) Totalise any column" 
330 PRINT" (K) End program" 

340 LOCATE 1,23 

350 CHOICE$S="ABCDEFGHIJK":GOSUB 460 
360 CLS:L%=mainsize%: subsizeZ=mainsizez 
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IF mainsizeZ=0 THEN PRINT"File empty":GOSUB 23 


60: RUN 


380 


ON SEL% GOSUB 830,950, 1190, 1350, 1420, 1500, 1490 


11940,2040,2140,410 


390 
400 
410 
420 
430 
440 
450 
460 
470 
480 
490 
500 
510 
520 
530 
540 
550 
560 
570 
580 
590 
600 
610 
620 
630 
640 
650 
660 
670 
680 
690 
700 
710 
720 
730 
740 
750 
760 
770 
780 
790 
800 
810 





IF SELZ=9 THEN GOSUB 2360 
GOTO 190 

SPEED WRITE O 

INK 0,1: INK 2,20 

END 

REM MENU SELECTION VALIDATION 
PRINT"Select Option"; 

SELZ=0 

WHILE SEL%=0 

KS=UPPERS (INKEY#) 

IF K$<>"" THEN SELZ=INSTR (CHOICES ,K#) 
WEND 

RETURN 


REM CREATE FILE 

PRINT"Enter file size (number of records) 
low=1:high=1000:GOSUB 3240 

filesizeZ=K7% 

PRINT"Enter number of fields required (2-15)" 
low=2:high=15:GOSUB 3240 

fields%=KZ-1 

DIM A#$(fieldsZ,filesizeZ%) 

CLS 

FOR F%Z=0 TO fields% 

PRINT"Enter field heading "53F%+1 

GOSUB 2250: A¢(FZ,0) =K¢ 

NEX™ 

GOSL.| 1190 

RETURN 


REM LOAD FILE 

INPUT"Enter filename "3; filename? 
OPENIN filenames 

INPUTS#9 , filesize%,fields%,mainsize% 
DIM A#(fields%,filesizeZ) 

FOR RZ=0 TO mainsizeZz 

FOR F%=0 TO fields~% 
INPUT#9 , AS (FZ,RZ) 

NEXT: NEXT 

CLOSEIN 

RETURN 





160 Filing information 


820 REM SAVE FILE 

830 INPUT"Enter filename ";filenamet 

840 SPEED WRITE 1 

850 OPENOUT filenames 

860 WRITE#S,filesizez,fieldsZ,L% 

870 FOR RZ=0 TO L% 

880 FOR F%Z=0 TO fields% 

890 WRITE#9 ,AS(F2Z,R%) 

900 NEXT:NEXT 

910 CLOSEOUT 

920 RETURN 

930 ' 

940 REM DISPLAY FILE 

950 F%Z=1: top%=1 

960 WHILE INKEY(47)<>0 

970 CLS:PRINT"Press space bar to regain menu" 
980 GOSUB 2320 

990 PEN 2:PRINT A#(0,0) TAB(20) AS(FZ,0):PEN 1 
1000 GOSUB 2320: bottom%Z=top%+19 

1010 IF bottomZ>L% THEN bottomZ=Lz% 

1020 FOR RZ=top% TO bottom” 

1030 PRINT A$(O,RZ) TAB(20) AS(FZ,RZ) 

1040 NEXT 

1050 CALL &BBOS: ‘KM RESET 

1060 CALL &BB18: ‘KM WAIT KEY 

1070 IF INKEY(8)=0 THEN FY%=F2Z-1 

1080 IF INKEY(1)=#0O THEN F%=F%+1 

1090 IF INKEY(0O)=0 THEN top%=top%-—20 

1100 IF INKEY(2)=0 THEN top%=top%+20 

1110 IF F2%<1 THEN F4=fields% 

1120 IF F42>fields% THEN F%=1 

1130 IF top%<1 THEN top%=CINT (LZ/20) #20) +1 
1140 IF top%>L% THEN top%=1 

1150 WEND 

1160 RETURN 

1170 ’ 

1180 REM ADD RECORDS 

1190 WHILE mainsizeZ%<filesize% AND FRE(O) > fields 
24%100 

1200 mainsizeZ=mainsize%+1:F%=-1 

1210 CLS:PRINT" Type EXIT to finish entry of recor 
ds" 

1220 PRINT:PEN 2:PRINT"Record No :"mainsize% TAB(2 
0) "Bytes Free :"FRE(O):PEN 1 

1230 WHILE F%<fields% 

1240 GOSUB 2320 

1250 F“%=F%+1 
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1260 PRINT"Enter "s;AS(F2%,0) 
1270 GOSUB 2250: AS (FZ,mainsizeZ) =Kt 

1280 IF AS(F%,mainsize%~)="EXIT" THEN mainsizeZ=mai 
nsizeZ-1:GOTO 1320 

1290 WEND 

1300 WEND 

1310 PRINT:PRINT"File full":GOSUB 2340 


1320 RETURN 
1330 ° 


1340 REM MODIFY RECORD 

1350 GOSUB 2040 

1360 GOSUB 2410 

1370 PRINT"Enter new "AS$(FZ,0) 

1380 GOSUB 2250: AS(F7,RZ) =K¢ 

1390 RETURN 

1400 ° 

1410 REM DELETE RECORD SUBROUTINE 

1420 GOSUB 2040 

1430 PRINT"Record to be deleted (Y/N)?" 

1440 KS=INKEY$: IF K$=""" THEN 1440 

1450 KS=#UPPERS (KS) 

1460 IF K$="Y" THEN WHILE RZ<mainsize%Z:FOR F~Z=0 TO 
fields%:AS(FAZ,RZ) =AS(FZ,RA~+1) s NEXT: R“Z=R4+1:WEND: m 
ainsizeZ=mainsizeZ-1 

1470 RETURN 


1480 
1490 REM QUICKSORT FILE 


1500 GOSUB 2410 

1510 CLS:PRINT"Sorting by ";AS(FZ,0) 
1520 DIM stack1%(16) ,stack2% (16) 
1530 sp%=0: headZ=1:tailZ=L% 


1540 WHILE head%<tail% 
1550 pivot$=A$ (FZ, (head%~+tail%) \2) 


1560 a%=head%:b%=tail% 
1570 WHILE AS(F%,a%)<pivot$: a4=a%+1:WEND 

1580 WHILE AS(F%,b%) >pivot$:b%=b%-1: WEND 

1590 IF a%<b% THEN FOR CZ%=0 TO fields%:t$=A$(C%,a% 
)2:A$(CZ%,a%) =AS$(CZ,bZ) SAS (CA, BZ) =tS$2 NEXT: at=a%+1:2b% 
=b%Z-1:GOTO 1570 

1600 IF a%=b% THEN 1t%=b%-1:shh%=a%Z+1 ELSE 1t%=b%:h 
hZ=aZ 

1610 spZ=sp%t+13: lh“Z=headZ:htz%=tailZ% 

1620 IF 1t%-1h%<ht%-hh% THEN stack1%(sp%) =hhZ: stac 
k2% (sp%) *ht%:headZ=1h“4:tail“Z=1t% ELSE stack1%(sp%) 
=lh%: stack2Z (sp%) =1t%:head%Z=hhZ%: tail Z=ht% 

1630 WEND 

1640 IF sp%>0 THEN head%=stack1i%(sp%) stailZ=stack2 
24(sp%) :sp%Z=sp%-1:GOTO 1540 
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1650 ERASE stacki%,stack2% 
1460 RETURN 

1670 ° 

1680 REM SEARCH FILE MENU 
14690 GOSUB 3140 

1700 LOCATE 1,5 

1710 PRINT"SHRINK subfile options" 

1720 PRINT"SEARCH any field":PRINT 

1730 PRINT"(1) <> key” 

1740 PRINT" (2) = key" 

1750 PRINT"(3) >= key" 

1760 PRINT"(4) < key” 

1770 PRINT"(5) Character group" 

1780 PRINT:PRINT"Futher subfile options: "s:PRINT 
1790 PRINT"(A) Save sub-file" 

1800 PRINT"(B) Display sub-file” 

1810 PRINT"(C) Sort sub-file by any field" 
1820 PRINT"(D) Delete sub-file from main file" 
1830 PRINT"(E) Totalise column" 

1840 PRINT" (F) Print sub-file" 

1850 PRINT"(G) Return to main menu" 

1860 LOCATE 1,24 

1870 CHOICES="12345ABCDEFG":GOSUB 440 

1880 CLS:L%=subsize% 

1890 ON SEL% GOSUB 2470,2670,2670, 2670, 2670,830,95 
0,1500,3070,2140,1940,1910 

1900 IF SEL%<12 THEN 1490 

1910 RETURN 

1920 ’ 

1930 REM PRINT FILE 

1940 FOR R%~=1 TO L% 

1950 PRINT#8:PRINT#8,"Record No :"R% 

1960 PRINT#8, STRINGS (40,"-") 

1970 FOR F~Z=0 TO fields% 

1980 PRINT#8,A$(F%,0) TAB(21) AS(F%,R%) 

1990 NEXT 

2000 NEXT 


2010 RETURN 
2020 ° 


2030 REM DISPLAY RECORD 

2040 F%#0:GOSUB 2540:CLS 

2050 PRINT"Current Record number"RZ 
2060 GOSUB 2320 

2070 FOR F24Z=0 TO fields” 

2080 PRINT AS(FZ,0) TAB(21) AS(FZ,RZ) 
2090 NEXT 

2100 GOSUB 2320 

2110 RETURN 


























































2120 
2130 
2140 
2150 
2140 
2170 
2180 
2190 
2200 
2210 
2220 
2230 
2240 
2250 
2260 
2270 
2280 
2290 
2300 
2310 
2320 
2330 
2340 
2350 
2360 
2370 
2380 
2390 
2400 
2410 
2420 
2430 
2440 
2450 
2440 
2470 
2480 
2490 
2500 
2510 
2520 
2530 
2540 
25590 
2560 
2570 
2580 
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REM TOTALISE COLUMN 

total=0 

GOSUB 2410 

FOR RZ2=1 TO LZ 

total=total+VAL (AS(FZ,RZ)) 
NEXT 

PRINT"Column total ="total 
PRINT"Column average="total/L% 
GOSUB 2360 

RETURN 


REM GET LINE INPUT 

LINE INPUT K% 

IF K#=""" THEN 2250 

K$=UPPERS (K$) 

IF LEN(K#)>18 THEN K#=LEFT$ (kK, 18) 
RETURN 





REM DRAW LINE 
PEN 3:PRINT STRINGS (40,CHR#(154))3:PEN 1 
RETURN 


REM HOLD DISPLAY 

PRINT"Press SPACE bar to continue" 
K$="""WHILE K$< >CHR$ (32) :KS=INKEY%: WEND 
RETURN 

REM FIND FIELD HEADING 

flagZ=0 

WHILE flag%Z=0:F%Z=—-1 

PRINT"Qperate on which field? (Give heading) 
GOSUB 2250 

WHILE F%<fields% AND flag%=0 

FY=FA+1 

IF K#=LEFT$ (AS(FZ,0) ,LEN(K#)) THEN flag%Z=1 
WEND 

IF #lag%Z=0 THEN PRINT"No such field" 

WEND 

RETURN 


REM FIND RECORD 

#lag%Z=0 

WHILE flag%=0:RZ=0 

PRINT"Give record entry under ";A#(FZ,0) 
GOSUB 2250 

WHILE RZ<L% AND flag%=0 
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2590 
2600 
2610 
2620 


2630 
2640 


2650 
2660 
2670 
2680 
2690 
2700 
2710 
2720 
2730 
2740 
2750 
2760 


2770 
2780 
2790 
2800 
2810 
2820 
2830 
2840 
2850 
2860 
2870 
2880 
2890 
2900 
2910 
2920 
2930 
2940 
2950 
2960 
2970 
2980 
2990 
3000 
3010 
3020 


3030 


untZ) 


RZ=RZ+1 

IF K$=LEFTS (AS(FZ,RZ) ,LEN(K#)) THEN flagZ%Z=1 
WEND 

IF flag%Z=0 THEN PRINT"Record not found” 


WEND 
RETURN 


REM SEARCH DIRECTOR 

GOSUB 2410 

CLS:PRINT"SEARCH to operate on "3;A$(FZ,0) 
IF SELZ%<S THEN PRINT"Give search key" 

IF SELZ=5 THEN PRINT"Give character group" 
GOSUB 2250: comp$=K$ 

countZ=0 

FOR RZ=1 TO subsize~% 

ON SEL% GOSUB 2800, 2840, 2880, 2920,2960 
NEXT 

IF count%Z=0 THEN CLS:PRINT"SEARCH is NEGATIVE 


"sGOSUB 2360 ELSE subsizeZ=count% 


RETURN 

REM SEARCH <> 

IF AS(FZ,RZ)<>comp$ THEN GOSUB 3000 
RETURN 


REM SEARCH = 
IF AS(FZ,RZ)=comp$ THEN GOSUB 3000 
RETURN 


REM SEARCH >= 
IF AS(FZ,RZ) >=comp$ THEN GOSUB 3000 
RETURN 


REM SEARCH < 
IF AS(FZ,RZ)<comp$ THEN GOSUB 3000 
RETURN 


REM SEARCH FOR CHARACTER GROUP 

IF INSTR(AS(FZ,RZ) ,comp$) <>O THEN GOSUB 3000 
RETURN 

REM MOVE RECORD 

countZ=countZ+1 

FOR CZ=0 TO fieldsz 

K$=A$ (CZ,RZ) SAS (CA,RZ) =AS (CZ, count%) :AS$(C%,co 
=K$ 

NEXT 
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3040 RETURN 

3050 ' 

3060 REM DELETE SUB FILE 

3070 IF subsizeZ=mainsize% THEN 3120 

3080 FOR RZ=subsizeZz+1 TO mainsize% 

3090 FOR FZ=0 TO fields% 

3100 AS(F4,RZ~-subsizeZ) =AS(FZ,RZ) 

3110 NEXT:NEXT 

3120 mainsizeZ=mainsizeZz—subsizeZ: SELZ=12 
3130 RETURN 

3140 ° 

3150 REM TITLE 

3160 CLS 

3170 LOCATE 1,2 

3180 GOSUB 2320:PEN 2 

3190 PRINT" GENERAL PURPOSE DATA FILING SYSTEM 


3200 GOSUB 2320:PEN 1 

3210 RETURN 

3220 ' 

3230 REM INTEGER INPUT VALIDATION 

3240 INPUT K 

3250 IF K<>INT(K) THEN PRINT"Input not an integer" 
:GOTO 3240 

3260 IF K<low OR K>high THEN PRINT"Input out of ra 
nge":GOTO 3240 

3270 KZ=K 

3280 RETURN 








Using the program 

There are two menus, a small primary menu of three options and a 
main menu of 11 options. On first running the program, the 
primary menu is displayed: 


1 Create new file 
2 Load existing file 
3 Exit program 


Until data files have been prepared, Option 1 is the only choice 
open. However, if files do exist on tape and we want one of them 
back, we would select Option 2, Load file. 
Create file (option 1): When creating a new file, the leading parti- 
culars, such as the number of records, the number of fields and the 
literal headings of each field must be obtained from the user. 
File size: The first screen prompt is ‘Enter file size (number of 
records)’. 

We shall see later that as records are entered into the file, the 
screen continuously displays the file status, including the number of 
bytes still free in RAM. 
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Number of fields: The next screen prompt is ‘Enter number of fields 
required (2-15)’. The maximum number is fixed at 15 and the 
minimum at 2. A trap is included to prevent the limit being 
exceeded. 

Field headings: Each field must have a heading, otherwise the data 
within the field has no meaning. A different heading is required for 
each field so the screen prompt for, say, field 4 is ‘Enter field 
heading 4’. The program ignores, without warning, characters in 
excess of 18 per field. It doesn’t matter if field headings are entered 
in lower or upper case because the program converts all input to 
upper case. Once the leading particulars of a new file have been 
entered, the display immediately changes to Option C in the Main 
menu which is ‘Add records’. 


Main menu options 

Save file (Option A) The first prompt is ‘Enter file name’, the limit 
being 16 characters for tape and 8 characters for disc. Instructions for 
operating the tape transport, where necessary, will appear after an 
acceptable file name is received. The listing for the subroutine will 
work for both tape on the CPC 464 and disc on the CPC664 without 
any modifications. 

Display file (Option B): Assuming the file has only three records, each 
giving Name, Occupation and Nationality, the screen display would 
appear something like this: 


Press space bar for menu 
NAME OCCUPATION 


KYFFIN G TV ENGINEER 
SMYTHE-SOPERS F LABOURER 

SOLOBINUS Z BALLET DANCER 
etc etc etc etc 
















NAME is the fixed keyfield on the left of the screen but the second 
field, OCCUPATION, can be rotated in favour of one of the other 
fields by use of the left or right cursor keys. For example, if we 
pressed the left cursor key, the display above might change to: 





Press space bar for menu 
NATIONALITY 


KYFFIN G BRITISH 
SMYTHE-SOPERS F PERUVIAN 
SOLOBINUS Z BRITISH 

etc etc etc etc 











There is only room for displaying 20 records at a time but any 
remaining blocks of 20 can be moved into view by use of the Up/ 
Down cursor keys. If the display is moved beyond the boundaries of 
the fields or records, wrap-around occurs. That is to say, if there were 
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7 fields and we tried to shift in a non-existent 8th field, the display 
would wrap around to the second field again. 

Add records (Option C): Assuming the file has the three field headings 
Name, Occupation and Nationality, the screen would prompt as 
follows: 

NAME . . .assumed answer ‘Kyffin G’ 

OCCUPATION . . . assumed answer ‘TV Engineer’ 
NATIONALITY . . . assumed answer ‘British’. 

When the last data item has been entered, the screen clears ready 
for the next record to be entered. If there are no further records to be 
added during the current session, keying EXIT will regain the 
menu. If the number of records reaches the maximum estimated 
during the creation stage, or if the bytes free are uncomfortably low, 
the message ‘File full’ will appear and further records rejected. 
Modify any field (Option D): This option allows you to modify any 
field of a selected record. The first prompt is ‘Give record under 
NAME’ (assuming, of course, that the key field is NAME). The first 
letter or two of the key field is sufficient to initiate the search. The 
existing record is then displayed. The next prompt is to enter the 
new field contents. Any reusable text from the old field can be 
reclaimed by detaching the copy cursor by pressing the SHIFT and 
cursor keys simultaneously and then using the copy key. 

Delete record (Option E): After asking for the record, it is displayed in 
full followed by the message ‘Record to be deleted Y/N’. The chance 
to change your mind is thus offered if N is entered. 

Sort by any field (Option F). Option F in the main menu (or C 
in the Sub-file menu) will sort a file into order by any field 
heading. The particular algorithm used is called QUICKSORT. 
Its performance can approach the theoretical maximum sorting 
speed for continuous lists (arrays). The subject of sorting is treated 
in Chapter 9. In the meantime, it is simply a case of responding to 
the prompt ‘Operate on which field?’. If we sort under NAME, it 
will put all records into alphabetical order by name. On the other 
hand, a sort under AREA will be numerical although the numbers 
are still held in string form. Because of this, it is important, when 
creating a file, that all numerical data entered should have the same 
total number of digits. Small numbers must have leading zeros 
added as packing. If this is not done, numeric sorts will not be 
carried out correctly. To see why this is, examine the following 
series of numbers: 

54 
763 
15777 
894 
If these are stored in string form, the sorting proceeds from the 
ASCII code of the most significant character towards the least signifi- 
cant. In the above example, the first characters examined will be the 
codes for 5, 7, 1 and 8 because they take precedence over the less 
significant characters. Subsequently, if the numbers are to be sorted 
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into descending order, the computer would judge the following 
order to be correct: 
894 
763 
54 
15777 
If the numbers had been originally entered with enough leading 
zeros to make all numbers 5 characters long, the sort would yield 
the following correct result: 
15777 
00894 
00763 
00054 
Create subfile (Search any field) Option G: On selecting Option G, an 
alternative menu is displayed. The first half of the menu offers five 
ways of selecting which records from the main file are to be treated 
as a ‘subfile’. Building up a subfile from records which share one or 
more common attributes is a powerful feature of the program. 
Assume the file loaded from store is named MUNICIPAL and 
contains three fields — DISTRICT, POPULATION and RATEABLE 
VALUE. We wish to find a district with a population greater than 
100,000 and with a rateable value less than 20 million pounds. The 
task begins by selecting Option G which brings out the following 
search menu: 


SHRINK subfile options 


SEARCH any field 
(1) <> key 

= key 

>= key 

< key 

Character group 
Further subfile options: 
(A) Save sub-file 
(B) Display sub-file 
(C) Sort subfile by any field 
(D) Delete subfile from main file 
(E) Totalise column 
(F) Print subfile 
(G) Return to main menu 
Selection option 





The steps from then on could vary but the following approach is 
reasonable: 


1 Select Option 3 which is ‘greater than or equal’ to. The first 
prompt will then be: 

Operate on which field? (Give heading) 
The response should be POPULATION (or just P will suffice). 
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2 The next prompt will be: 

Search to operate on POPULATION 

Give search key 
The response should be 100000 
On selecting option B (Display sub-file), the subfile is displayed 
with all districts with a population greater than or equal to 100,000. 
The search menu is now regained (by pressing the SPACE bar). The 
subfile can now be shrunk still further. 
3 Selection Option 4 which is ‘less than’. The first prompt will then 
be: 

‘Operate on which field? (Give heading)’ 
The response should be ‘RATEABLE VALUE’ (or just ‘R’ will do.) 
4 The next prompt will be: 

Search to operate on RATEABLE VALUE. 

Give search ke 
The response should be 20000000 


On selecting Option B (Display subfile), the new subfile is displayed 
with all districts having a population greater than or equal to 100,000 
and with rateable values less than 20 million. We could, of course, 
shrink still further by using Option 5 (Character group) and 
insisting that the district name must contain the substring ‘fie’. 
According to our own file on MUNICIPAL (compiled with the help 
of Whitaker’s Almanac), the final shrinkage pointed to the district of 
ASHFIELD. The example is illustrated in Figure 7.2 


Main file 


MUNICIPAL 
Ist shrink 







2nd shri 
>N SARs 3rd shrink 


Ca . Name contains 
Rateable value ‘fie 
< 20 million 






Population 


> 100,000 


Fig 7.2 


The second half of the search menu offers several straightforward 
options, including save, and sort the subfile at any stage. They are 
used in exactly the same manner as their counterparts in the main 
menu. The ability to split the main file, by using Option D (Delete 
sub-file from main file) is very useful when the main file grows too 
large for RAM. For example, we can create a sub-file of all districts 
which begin with letters alphabetically lower than ‘N’. The sub-file, 
after being saved under another file name, can then be deleted from 
the main file. It then becomes a new ‘main file’ and the original file, 
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now much depleted, can be saved separately. 

Print file (Option H): This prints out hard copy of the entire file. 

Display single record (Option I): Searches through the file for a chosen 

record. It displays the complete record with fields aligned vertically. 
Assuming we ask for the record on SOLOBINUS Z, the search 

would end with the following display: 


Current record number 2 


NAME SOLOBINUS Z 
OCCUPATION BALLET DANCER 
NATIONALITY BRITISH 


Press any key to continue 


The search requires the keyfield of the record to be entered. In the 
example case, the prompt would read: 

‘Enter entry under NAME’ 
Your response might have been the full name, SOLOBINUS Z. 
However, the program is user-friendly and doesn’t insist that you 
give the full name or even the exact spelling. The program will start 
searching on receipt of the first one or two letters of the keyfield. The 
search ends when the first record is found having a keyfield 
beginning with the same few letters you have entered. However, 
the fewer letters you enter, the greater will be the chance of bringing 
out an unwanted record which, by coincidence, begins with the 
same letters. If this happens, you can add another letter - if you 
know it — and start another search. If all this fails, the last resort 
would be to go over to the Display File option, skim through the 
keyfields until the full name is found and then return to Option I for 
a new search. If a search through the file fails to find a record which 
corresponds to the given search letters, the message ‘No such 
record on file’ is displayed. 
Totalise any column (Option J): This prints out the column total, under 
a chosen field heading, together with the average value. Clearly, 
this option is only applicable to numerical fields. Alphabetical fields 
will yield a zero result. 
End program (Option K): This option correctly terminates the program 
and sets the cassette writing speed and inks to their default values. 





How the program works 


The first, and relatively small part of the program, will be recog- 
nised as a self-contained control section. The remainder of the 
program is simply a collection of subroutines, called as needed from 
the control section. Some of the subordinate subroutines will have 
already been treated in Chapter 3 so they do not justify detailed 
treatment again. Some of the subroutines were tailor-made to suit 
Program 7.1, but many of them would be suitable for splicing into 
other programs, either as they stand or slightly modified. 
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Variable names used in Program 7.1 

The complete data file is stored on tape under the following four 
variable names: 

A$(F%,R%)=two-dimensional array holding all records of the file 
filesize% =maximum number of records that can be stored in the 
main file 

fields% =number of fields in file 

L% =temporary variable set to the current number of records in the 
file or sub-file. 

Other variables: 

mainsize% =current number of records in main file 

subsize% =current number of records in sub-file 

filename$=name of file 

K$=general purpose global variable 

total=summation of field values 

F%=current indexed field number 

R%=current indexed record number 

A$(F% ,0)=heading of field F% 

SEL% =menu option number selected 

bottom% =bottom of display 

top%=top of display 


Subroutine DRAW LINE (GOSUB 2320) 
See Chapter 3. 


Subroutine GET LINE INPUT (GOSUB 2250) 
When a screen prompt requests string input from the keyboard, 
some responses will be unacceptable. This subroutine rejects the 
null string caused by an operator mistakenly pressing the ENTER 
key before entering text. The use of LINE INPUT is preferable in 
filing programs because text often contains punctuation and other 
characters which the ordinary INPUT statement would reject. The 
text is entered into a temporary global variable K$. After the 
subroutine has returned, the text in K$ is normally assigned to 
another variable. The subroutine allows an operator the freedom to 
enter text in either upper or lower case. Use has been made of the 
command UPPERS which ensures that all input text, irrespective of 
whether it was entered in upper or lower case, is converted to upper 
case. It is important, when sorting alphanumeric text, that all 
characters be in the same ‘case’. Because sorting is carried out on 
ASCII values, mixed-case text would produce weird results. 

The subroutine restricts the length of all input to 18 characters by 
cutting off (truncating) characters in excess, rather than rejecting the 
entire input. 


Subroutine HOLD DISPLAY (GOSUB 2360) 

This employs the widely known dodge for freezing a display or 
halting a program until the operator is ready. Note the appearance 
again of the general purpose variable, K$. 
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Subroutine SAVE FILE (GOSUB 830) 

Outline information on opening and closing files has already been 
given. This is a complete subroutine for writing a data file to tape. It 
assumes certain information resides in the following variables 
before it is called: 


Maximum number of records allowed=filesize% 
Maximum number of fields allowed=fields% 

Current number of records=L% 

All text to be stored in the array, A$(fields%,filesize%) 


The first two variables, constituting the heading information, are 
written because they will be needed to feed the DIMension state- 
ment when the data file is read back at some later date. The third 
item L%, representing the current number of records in the file, is also 
needed as a FOR/NEXT loop parameter when reading back the file 
array. The inner loop writes the fields of each record and the outer 
loop takes care of the complete records. No screen prompts are 
required for operating the tape unit because they are issued 
automatically by the OPEN statement. The WRITE#9 command 
is used each time. 


Subroutine LOAD FILE (GOSUB 710) 

After a preliminary call for the file name, the three items of heading 
information are read in. The first two variables are identical to those 
used in the SAVE subroutine but the third, although it was saved 
under the name L%, is changed to mainsize%. The reason for this 
may be obscure at the moment but it is all to do with options which 
distinguish between a main file and a subfile. The nested FOR/ 
NEXT loops for reading in the array are identical in form to the 
SAVE subroutine except, of course, for the substitution of INPUT 
#9 in place of WRITE #9. 


Subroutine DISPLAY FILE (GOSUB 950) 

This subroutine displays pages of the file in broadsheet form. (Refer 
back to ‘Using the program’). The rather mysterious CALL &BBO03 
is a machine code routine in the operating system which, among 
other things, clears out (resets) the keyboard buffer. The other 
machine code call to &BB18 is KM WAIT KEY (wait for next key). 
The letters ‘KM’ in the appended REMarks refer to the ‘Keyboard 
Manager’ and is the group name given by the designers of the 
system ROM to certain operating system routines. 

By convention, the headings of the fields, for example NAME, 
OCCUPATION, NATIONALITY etc, are stored in the ‘Record 0’ 
elements of the main array. A$(0,0) is the keyfield heading and 
A$(F%,0) is the heading of field F%. Lines 1020 to 1040 display two 
fields of data in up to 20 records at a time. Note that the bulk of the 
subroutine lies within the confines of a WHILE/WEND loop which 
is testing for a SPACE BAR press (key 47). The four other INKEY 
lines which lie further down are testing for a cursor key press. 
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Subroutine FIND RECORD (GOSUB 2540) 

The field number, F%, must be passed as a parameter because the 
search is conducted for a particular record under a chosen field 
heading. If the search is by keyfield, then F% will be passed as 0. 
Assuming the keyfield heading is NAME, the first prompt will read, 

‘Give record entry under NAME’ 

The response from the keyboard is entered into K$, by a call to GET 
LINE INPUT. Line 2600 must be given the credit for injecting a 
degree of user-friendliness into the keyboard response. The first 
letter, or first few letters, of the name entered into K$ is sufficient for 
the search. For example, if the record under name was KYFFIN G, 
the letters KY might be sufficient for retrieving the record. The end 
product of the subroutine is the record number left in R%. The 
search carries on until the record is found or deemed to be not on 
file. 


Subroutine DISPLAY RECORD (GOSUB 2040) 

The subroutine first calls on FIND RECORD to obtain the record 
number in R%. The complete record is then displayed, headed by 
the current record number. 


Subroutine FIND FIELD HEADING (GOSUB 2410) 

Normally, a search through the file is conducted on the keyfield 
heading but this subroutine is needed to support searches under 
any field heading. The response to the prompt will be in K$ after a 
call to GET LINE INPUT. Line 2470, which should now be familiar, 
allows the operator the option of entering the first letter or two of 
the heading or in full. 


Subroutine PRINT FILE (GOSUB 1940) 

This subroutine simply prints out the entire file as hard copy, 
including the current record numbers. No provision is made for 
sending control characters to the printer because they are not stand- 
ardised on all models. It can be improved to suit the particular 
printer you have connected. The subroutine in the listing of 
Program 7.1 performs the absolute minimum. 


Subroutine TOTALISE COLUMN (GOSUB 2140) 

The column heading to be totalised is obtained by first calling on 
FIND FIELD HEADING followed by some simple arithmetic. Both 
the column total and the column average are printed out. Because the 
arithmetic is performed using VAL on a string variable, the result 
will be meaningless if the chosen column contains alpha characters. 


Subroutine QUICKSORT FILE (GOSUB 1500) 

Since the next chapter is devoted entirely to the subject of sorting 
and searching, no attempt will be made here to explain the sub- 
routine’s details apart from noting that it is based on the fast 
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QUICKSORT algorithm. Considering it is in BASIC, the perform- 
ance is reasonable but, for long files, an alternative ultra fast sort in 
machine code will be given in the next chapter. The heading, under 
which the sort is conducted, is obtained by a call to GET FIELD 
HEADING. The complete array A$(F%,R%) is sorted into order, 
lowest record first. 


Subroutine ADD RECORDS (GOSUB 1190) 
A file grows by adding more records. Unless checks are built in, the 
memory can suddenly overflow without warning. There are two 
mechanisms at work which can lead to this: 


1 The number of records can reach the limit imposed by an 
existing DIMension statement. 

2 The total number of bytes used can reach the limit imposed by 
the available RAM complement. 


If the amount of text per record is moderate, then the maximum 
allowed number of records will be the first limiting factor. On the 
other hand, the same number of records, each loaded massively 
with text, can cause an overflow earlier than expected. The sub- 
routine starts with the outer of the two WHILE/WEND loops which 
checks the current number of records already in the file and also the 
amount of RAM left after allowing for a healthy safety factor. The 
first line in the subroutine carries out both checks. The amount of 
safe RAM left has been arbitrarily decided by a constant safety factor 
equal to number of fields multiplied by 100. If the total free RAM is 
less than the constant, the message ‘File full’ is displayed and after a 
call to PRESS ANY KEY, the rest of the subroutine is skipped. 

The records are entered into A$(F%,R%) via a call to GET LINE 
INPUT. The data is entered, a field at a time, by a loop headed by an 
increment to the current field number F%. If the word EXIT is 
detected, the subroutine is terminated. While records are being 
entered, the current record number and the bytes left free are 
displayed at the top of the screen. 


Subroutine CREATE FILE (GOSUB 550) 

This subroutine takes care of the preliminary work necessary to start 
up a new file. The first two variables ‘filesize%’ and ‘fields%’ are 
obtained directly by asking for an estimate of the maximum number 
of records the file will eventually hold, and the number of fields 
respectively. This information is fed to the DIMension line. The 
headings for each field are then obtained via a call to GET LINE 
INPUT and assigned to the Record 0 position in the array. The first 
records in the newly created file are then entered by a call to ADD 
RECORDS. 


Subroutine MODIFY RECORD (GOSUB 1350) 
To modify a record, it is first found and then displayed by a call to 
DISPLAY RECORD. The field to be modified is then found by a call 
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to FIND FIELD HEADING. The modified field data is then entered 
by a final call to GET LINE INPUT. 


Subroutine TITLE (GOSUB 3160) 

This is a simple affair but still worth packing into a subroutine 
because it is used several times. The PEN and INK values can be 
changed to suit individual taste. 


Subroutine DELETE RECORD (GOSUB 1420) 
The record is first displayed by a call to DISPLAY RECORD. After 
final confirmation from the operator, the record is deleted from the 
file and the resultant hole in the file closed up. 


Subroutine SEARCH FILE MENU (GOSUB 1690) 

This is a subsidiary menu, which can be called as one of the options 
given in a main menu. The first call is to TITLE for heading the 
menu page. Options 1 to 4 allow a main file to be shrunk down toa 
sub-file containing only records which satisfy certain criteria defined 
by keyed operators. Option 5 assumes the criteria for inclusion into 
the sub-file is the presence of a particular character or group of 
characters. Note that selection of any one of these five options 
causes a call to the same GOSUB number 2670 which is the 
subroutine SEARCH DIRECTOR, now to be described. 


Subroutine SEARCH DIRECTOR (GOSUB 2670) 

To create a subfile, the operator must enter the field heading of 
interest so the first call is to FIND FIELD HEADING. The next 
prompt depends on the value in SEL%, a parameter passed from 
the subfile menu. 


1 If SEL% is either 1, 2, 3 or 4, the prompt is ‘Give search key’. 
2 IfSEL% is 5, the prompt is ‘Give character group’. (Note: If A, B, 
C, D, E or F is selected, it indicates the request was one of the 
‘Further subfile options’ which does not require the aid of the 
SEARCH DIRECTOR.) 


The response to either of the prompts is assigned to the variable, 
comp$, via a call to GET LINE INPUT. (comp$ is so named because 
it contains the parameter used for comparison with each record in 
the main file.) A separate subroutine for each of the comparisons is 
called from within the FOR/NEXT loop. Although the loop extends 
from R%=1 to subsize% it covers the whole of the main file on the 
first call because subsize% will have been previously assigned to 
mainsize%. All records which match the entered data in comp$ are 
brought out to the front of the main file with the aid of subroutine 
MOVE RECORD. Because the subfile is the collection of records 
now at the front of the main file, no additional RAM space is 
occupied. The variable, subsize%, holds the number of subfile 
records. 


175 


176 


Filing information 


Subroutine MOVE RECORD (GOSUB 3000) 
This is called from within SEARCH DIRECTOR and moves all 
records forming the subfile to the beginning of the main file array. 


Subroutine DELETE SUBFILE (GOSUB 3070) 

This subroutine is called only if the subfile is to be deleted from the 
main file. The clue to its operation can be seen in the FOR/NEXT 
loop starting parameter, subsize% +1. In other words, the mainfile 
now starts at the first record number higher than the end of the 
subfile. (You will remember that the records, collected into the 
subfile, were all repositioned at the head of the main file.) 


Initialisation and main menu 
This is the subroutine control section. It starts at line 10, finishes 
with the command END at line 430. It performs as follows: 


1 Reset initial states. Establish mode and border/ink colours. (We 
have found that the most appealing colour scheme for presenting 
the information is blue border with a black paper. However, this is a 
matter of personal taste.) 

2 Display primary menu, together with the prompt for selecting an 
option number, between 1 and 3. This is handled by line 160. The 
title at the top of the menu display comes via a call to subroutine 
TITLE. 

3. Display main menu. Once the main menu is gained, the primary 
menu is locked out so it is impossible to erase an existing file in 
RAM by loading in another file from tape or creating a new file. 

4 Revert to default baud and INKs. (After a call is made to SAVE 
FILE subroutine, the machine would be left in the 2000 baud 
condition.) 


Preparing an index 


Readers of non-fiction books expect, quite rightly, to find a detailed 
page index at the back. Novels are often read through from cover to 
cover and then dumped in the bottom of a cupboard. Technical 
books, on the other hand, lead a different life. Instead, they are 
consulted at odd times, usually when some specific fact or term 
needs clarification. In such circumstances, a book, however out- 
standing in scholarship and style, will be branded ‘useless’ if the 
elusive term or idea cannot be found quickly. A mediocre book with 
a good index may be more helpful in the long run, particularly to a 
student, than a first class book spoilt by a skimpy index. 

The preparation of an index is time-consuming and, to put it 
mildly, lacking in motivation. Obviously the index cannot be 
prepared at the manuscript stage because the page numbers will 
bear little resemblance to the final typeset version, consequently, 
the index must be prepared after the page proofs arrive from the 


Preparing an index 


typesetters and before they are sent back to the publishers. Most of 
this time is taken up by proof reading so the index is often a last 
minute rush to avoid breaking a deadline. 


Index methods 
There are two types of index: 


1 The item is followed by the page number where it first appears. 
This is relatively easy to implement but, in the worst case, consists 
of little more than a list of paragraph headings. 

2 The item is followed by all the page numbers where the item is 
mentioned. This is far more useful but obviously involves a lot of 
painstaking work if done by hand. 


In what follows, we assume method (b) is the only one worth 
considering. 


Hand preparing 

To highlight the difficulties, assume that you have a fat tome of, say, 
300 pages in front of you. It has no index but you are going to make 
one. Suppose the first item worthy of inclusion you come across on 
page 1 is the word ‘structure’. This is a common and highly emotive 
word in computing so you would look through every page to the 
end of the book for all references to ‘structure’. This would take 
some time. But this is only one item! There may be a hundred or 
more items, each with a row of page numbers. A dismal prospect 
indeed. You may decide on another approach, whereby you go 
through all the pages putting down items indiscriminately and re- 
arranging them in order as a separate task at the end. Obviously, 
the computer can help. Even a general purpose filing system, such 
as our Program 8.1, could take away some of the drudgery by 
treating the index as a data file and taking advantage of the 
alphabetical sort option. Unfortunately, it couldn’t add that final 
touch. It could sort the items in order but we would still be left with 
the task of formatting. That is to say, multiple appearances of the 
same item must be formatted to a single appearance followed by a 
row of page numbers separated by commas. 


Index processing. 


A program, dedicated to the sole task of index preparation, is 
justified because it would benefit many groups apart from authors. 
For example, it could be used for existing reference books which 
have inadequate indexes. School and tech college teachers might 
also find such a program helpful to provide indexes for sets of 
course notes, as indeed would students in the throes of revision. 
Indexes are also a useful accompaniment to business and scientific 
reports. 

Examination of the listing of Program 7.2 reveals a superficial 
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resemblance to the previous filing program. Indeed, some of the 
same general purpose subroutines are again brought into service. 
This is not surprising because we still need to save, load, display, 
sort and amend an index data file. The main difference is that the 
‘records’ now become index items and one of the extra options must 
deal with the special problem of formatting. 


Program 7.2 


10 REM RAM INDEX PROCESSOR 

20 REM SUITABLE FOR CASSETTE OR DISC 
30 REM ON AMSTRAD CPC464 & CPC&44 
40 °‘ 

SO INK 0,0: INK 2,18 

60 MODE 1 

70 DIM BZ(100) 

80 L%Z=0 

90 GOSUB 2080 

100 LOCATE 1,7 

110 PRINT"PRIMARY INDEX MENU" 

120 LOCATE 1,12 

130 PRINT"(1) Create new index" 
140 PRINT"(2) Load existing index" 
150 PRINT"(3) Exit program" 

160 CHOICE$="123":GOSUB 410 

170 CLS 

180 ON SEL% GOSUB 510,420,360 

190 GOSUB 2080 

200 LOCATE 1,7 

210 PRINT"MAIN INDEX MENU" 

220 LOCATE 1,10 

230 PRINT"(1) Save index" 

240 PRINT"(2) Display index" 

250 PRINT"(3) Add items to index" 
260 PRINT" (4) Modify indexed item" 
270 PRINT"(S) Delete indexed item" 
280 PRINT"(6) Format index" 

290 PRINT"(7) Print index" 

300 PRINT"(8) End Program" 

310 CHOICES="123454678":GOSUB 410 
320 CLS 

330 IF L%Z=0O THEN PRINT" Index empty":GOSUB 1900: RUN 
340 ON SEL% GOSUB 740,860, 1080,1210,1290, 2230, 1560 
7360 

350 GOTO 190 

360 SPEED WRITE O 

370 INK 0,1: INK 2,20 

380 END 
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REM MENU SELECTION VALIDATION 

LOCATE 1,21 

PRINT"Select Option"; 

SELZ=0 

WHILE SELZ=0 

KS=UPPER$ (INKEYS) 

IF K#<>"" THEN SELZ=INSTR (CHOICES, K#) 
WEND 

RETURN 

REM CREATE INDEX 

GOSUB 1840:PRINT"CREATE INDEX":GOSUB 1840 
PRINT"Enter ESTIMATE of index size: (1—-2000)" 
low=1:high=2000:GOSUB 2160:sizeZ=K%Z% 

DIM A#(sizeZ~+1) 

PRINT"Enter INDEX heading" 
limit%=38:GOSUB 1740 

AS (0) =K 

GOSUB 1080 

RETURN 


REM LOAD INDEX 

GOSUB 1840:PRINT"LOAD INDEX":GOSUB 1840 
INPUT"Enter filename ";filenamet 
OPENIN filenames 

INPUT#9 ,sizeZ%,L% 

DIM A#(sizeZ+1) 

FOR R%~=0 TO L% 

INPUT#9 , A (RZ) 

NEXT 

CLOSEIN 

RETURN 

REM SAVE INDEX 

GOSUB 1840:PRINT"SAVE INDEX":GOSUB 1840 
INPUT"Enter filename ";filenamet 
SPEED WRITE 1 

OPENOUT filename? 
WRITE#9,sizeZ,Lz 

FOR RZ=0 TO LZ 

WRITE#9 , AS (RZ) 

NEXT 

CLOSEOUT 

RETURN 


e 


REM DISPLAY INDEX 
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860 WINDOW#1,1,40,1,6 

870 WINDOW#0,1,40,6,25 

880 RZ=1 

890 WINDOW SWAP 0,1 

900 PRINT"Press SPACE bar to regain MENU" 

910 PRINT"Press large ENTER key to SCROLL index" 
920 GOSUB 1840:PRINT A$(0):GOSUB 1840 

930 WINDOW SWAP 0,1 

940 WHILE INKEY(47)<>0 

950 FXZ=INSTR(A¥S(RZ) ,",") 

960 PEN 2:PRINT LEFTS#(AS(R%) ,F%-1) 5 

970 PEN 1:PRINT USING "&"3; RIGHTS (A$ (RZ) ,LEN(AS(R%) 
)-F%+1) 

980 CALL &BBOS: ‘KM RESET 

990 WHILE INKEY(18)<>0 AND INKEY(47)<>0 

1000 WEND 

1010 R%Z=RA~+1 

1020 IF RZ>L% THEN RZ=1:PEN 3:PRINT"End of index : 
Repeat display below":GOSUB 1840 

1030 WEND 

1040 WINDOW#O,1,40,1,25 

1050 RETURN 

1060 ° 

1070 REM ADD TO INDEX 

1080 WHILE L%<sizeZ% AND FRE(O) > 2000 

1090 CLS:GOSUB 1840:PRINT"ADD TO INDEX":GOSUB 1840 
1100 L%Z=L%+1 

1110 PRINT"Type EXIT to terminate entries" 

1120 PRINT:PEN 2:PRINT" Item number:"L% TAB(20) "By 

tes Free :"FRE(0O):PEN 1 

1130 PRINT: PRINT"Enter item" 

1140 limitZ=40:GOSUB 1740: A$(L%) =K$ 

1150 IF K$<>"EXIT" THEN PRINT"Enter page number": 1 

ow=1shigh=2000:GOSUB 2140: M$=RIGHTS (STR$(K%) ,LEN(S 

TRS (KZ) )-1) Ss AS(LZ%) =AS(LZ~) +", "+M$ ELSE L%=L%-1:G0TO 
1180 

11460 WEND 

1170 PRINT:PRINT"Index full":GOSUB 1900 

1180 RETURN 

1190 ° 

1200 REM MODIFY INDEX ITEM 

1210 GOSUB 1840:PRINI"MUDIFY INDEX LIEM":SGUSUB 184 

ce) 

1220 GOSUB 1440 

1230 PRINT"“Enter modification" 

1240 IF RZ=O0 THEN limitZ=38 ELSE limit%Z=255 

1250 GOSUB 1740: A#(RZ) =K$ 
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1260 RETURN 

1270 ‘ 

1280 REM DELETE INDEX ITEM 

1290 GOSUB 1840:PRINT"DELETE INDEX ITEM":GOSUB 184 
c?) 

1300 GOSUB 1460 

1310 PRINT"Entire item to be deleted (Y/N)?" 

1320 K$=INKEY$: IF K$=""" THEN 1320 

1330 KS=UPPER$ (KS) 

1340 IF K#$="Y" THEN WHILE RZ<L2Z: AS (RZ) =AS(RZ+1) 2 RZ 
=RZ+1:WEND:L“~=LZ-1 

1350 RETURN 

1360 ‘ 

1370 REM STRING QUICKSORT 

1380 PRINT"Processing: Please wait" 

1390 DIM stack12%Z(14) ,stack2%(16) 

1400 sp%=0: headZ=1: tail Z=LZ% 

1410 WHILE headZ%<tail% 

1420 pivot$=A$ ( (head%+tail%) \2) 

1430 aZ=head%:b%=tail% 

1440 WHILE A#(aZ%Z)<pivot#: aZ=a%+1: WEND 

1450 WHILE A$ (bz) >pivot$:bZ=bz%—1: WEND 

1460 IF aZ%<b% THEN t$=A% (aZ) = AS (aZ) =AS (bZ) AS (DZ) = 
t$:aZ=a7%+12:b%=b%-1:GOTO 1440 

1470 IF a%=b% THEN 1t%=b%-1:hh“4=a%+1 ELSE 1t%=b%sh 
hZ=a% 

1480 sp%Z=sp%t1:1lh“Z=headZ:htZ=tailZ% 

1490 IF 1t%-1h%Z<ht%—-hhZ% THEN stack1%(sp%) =hh%: stac 
k2%(sp%Z) =ht%ZsheadZ=1h%Z:tailZ~=1t% ELSE stack1%(spZ) 
=1h%: stack2%(sp%) =1t%:head%Z=hhZ: tail Z=htZ% 

1500 WEND 

1510 IF sp%>0 THEN head%=stack1%(sp%) stailZ=stack2 
%(sp%) :sp%=spz%-1:GOTO 1410 

1520 ERASE stack1%,stack27% 

1530 RETURN 

1540 ° 

1550 REM PRINT INDEX 

1560 GOSUB 1840:PRINT"PRINT INDEX":GOSUB 1840 

1570 WIDTH 50 

1580 PRINT#8,A$ (0) 

1590 PRINT#8 

1600 FOR RZ=1 TO L% 

1610 PRINT#S , AS (RZ) 

1620 NEXT 

1630 RETURN 

1640 ° 

1650 REM DISPLAY INDEX ITEM 
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1440 
1670 
1680 
1490 
1700 
1710 
1720 
1730 
1740 
1750 
1760 
1770 
1780 
1790 


1800 
omma 
1810 
1820 
1830 
1840 
1850 
1860 
1870 
1880 
1890 
1900 
1910 
1920 
1930 
1940 
1950 
1960 
1970 
1980 
1990 
2000 
2010 
2020 
2030 
2040 
2050 
2060 
2070 
2080 
2090 
2100 





GOSUB 1950:PRINT 

PRINT"Current index item number"RZ% 

GOSUB 1840 

PRINT AS(RZ) 

GOSUB 1840 

RETURN 

REM GET LINE INPUT 

K#="""WHILE K$="" 

LINE INPUT K# 

WEND 

KS=UPPERS$ (K#) 

IF LEN(K#) >limit% THEN K#=LEFT#(K$%,limit%) 
IF limitZ=255 AND INSTR(K$,",")=0 THEN PRINT" 


No comma : Enter again":GOTO 1740 


IF limitZ=40 AND INSTR(K#,",")>0 THEN PRINT"C 
illegal : Enter again":GOTO 1740 

RETURN 

REM DRAW LINE 

PEN 3 

PRINT STRINGS (40, CHR$(154)); 

PEN 1 

RETURN 


REM HOLD DISPLAY 

PRINT"Press SPACE bar to continue" 
K#=""SWHILE K#< >CHR$ (32) :K$=INKEY$: WEND 
RETURN 

REM FIND ITEM 

flag%Z=O: WHILE flagZ%=0 

R“Zz=-1 

PRINT"Enter characters to distinguish item" 
limitZ=100:GOSUB 1740 

WHILE RZ<L% AND flagZ%Z=0 

RZ=RZ+1 

IF K#=LEFT$ (AS(RZ) ,LEN(K#)) THEN flagZ=1 
WEND 

IF flag%Z=O THEN PRINT"Index item not found” 
WEND 

RETURN 


REM TITLE 

CLS 

LOCATE 1,2 

GOSUB 1840:PEN 2 
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2110 PRINT TAB(12);"INDEX Processor" 
2120 GOSUB 1840:PEN 1 

2130 RETURN 

2140 ' 

2150 REM INTEGER INPUT VALIDATION 
2160 INPUT K 

2170 IF K<>INT(K) THEN PRINT"Input not an integer" 
:GOTO 2140 

2180 IF K<low OR K>high THEN PRINT"Input out of ra 
nge":GOTO 2160 

2190 KZ=K 

2200 RETURN 

2210 ' 

2220 REM FORMAT INDEX 

2230 GOSUB 1840:PRINT"FORMAT INDEX":GOSUB 1840 
2240 GOSUB 1380 

2250 RZ=1: countZ=0: A$ (LZ+1)="" 

2260 WHILE RZ<=L% 

2270 GOSUB 2350 

2280 countZ=countZ+1 

2290 IF LEFT#(A#(RZ+1) ,F%)=ports THEN org#=port#:G 
OSUB 2410 ELSE A (count%) =As (RAZ) sRZ~Z=RZ4+1 

2300 WEND 

2310 L%Z=count% 

2320 RETURN 

2330 ‘ 

2340 REM SPLIT STRING 

2350 FZ=INSTR(AS(RZ) ,",") 

2360 port$=LEFT$ (AS (RZ) ,F%) 

2370 starboard$=RIGHTS (A$ (RZ) ,LEN(AS (RZ) )-FX%) 

2380 RETURN 

2390 ' 

2400 REM CONDENSE INDEX 

2410 MZ=0 

2420 WHILE port#=org# AND RZ~<=L% 

2430 K#=starboard%:GOSUB 2540 

2440 RZ=RZ+1 

2450 GOSUB 2350 

24460 WEND 

2470 GOSUB 2440 

2480 A$ (count%) =LEFT$ (org#,LEN(org#)-1) 

2490 FOR KZ=1 TO MZ 

2500 K#$=STR$ (BZ (KZ) ) 

2510 AS (count%) =A¥s (countZ) +", "+RIGHTS (K$,LEN (KS) -1 
) 

2520 NEXT 
2530 RETURN 
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REM COLLECT PAGE NUMBERS 
MZ=MZ+1 

BZ (MZ) =VAL (KS) 
FZ=INSTR(KS,",") 
K$=RIGHT$ (K$,LEN(K$) -FZ) 
IF F%>0 THEN 2560 
RETURN 


REM INTEGER SELECTION SORT 

FOR I%=MZ% TO 2 STEP -1 

PZ=1 

FOR J%=2 TO 1% 

IF BZ(IZ) >BZ(PZ) THEN P%=J% 

NEXT 

TZ=BZ (PZ) = BZA(P%) =BZ (1%) 2BA(IZ) =T% 
NEXT 

RETURN 





Primary index menu options 

Option 1: Create new index 

The first prompt is “Enter ESTIMATE of index size” (1-2000). The 
2000 limit refers to index items, irrespective of the number of page 
entries. The second and final prompt is for the index heading. If this 
is greater than 38 characters, the excess is stripped off. The program 
then switches automatically to option 3 in the Main index menu. 
Option 2: Load existing file. 

Use as described in Program 7.1. 


Secondary index menu 

Option 1: Save index 

Use as described in Program 7.1. 

Option 2: Display index 

On initial entry, only one index item is displayed. The ENTER key 
controls the scrolling. While it is held down, the display scrolls 
continuously but stops when it is released. The last item is identified 
by a line and “End of index” message. If the ENTER key is kept 
depressed at this point then the entire index display will be repeated 
as many times as needed. Press the SPACE bar to regain the menu 
at any time. 

Option 3: Add items to index 

The display is headed by the current index item number and the 
number of bytes still free, both of which are updated as additional 
items are added. The first input prompt is “Enter item” and the 
second is “Enter page number”. Characters entered in excess of 40 
are stripped off at the former stage. Comma separators will be 
positioned automatically by the program. Any commas input by the 
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user are rejected and followed by a message demanding complete 
re-entry of that item. 

Option 4: Modify indexed item 

The particular item to be modified is found and displayed by 
responding to the prompt “Enter characters to distinguish item”. 
Either the first, or first few characters, is normally sufficient for a 
successful search. The actual modification is achieved by either re- 
typing the complete item or detaching the COPY cursor (by simul- 
taneously pressing SHIFT and up-arrow cursor keys) and reclaiming 
any of the existing text. If the modified entry does not contain at 
least one comma the input is rejected. It is also possible to modify 
the Index heading although, in this case, commas are accepted and 
characters in excess of 38 stripped off. 

Option 5: Delete indexed item 

The procedure for deleting is the same as described for modifying 
the item. When the item is displayed, you will be asked to confirm 
by responding to an “Enter item to be deleted (Y/N)” prompt. A 
‘belt and braces’ approach, such as this, is often welcome when the 
delete option is selected by mistake. 

Option 6: Format index 

This is an easy to use option. All you have to do is wait. However, 
the process of formatting is complex, consisting of the following 
stages: 


1 All items are first sorted into order alphabetically. 

2 The entire index is scanned and all identically described items 
are condensed into a single entry with page numbers separated by 
commas. 

3 At the same time, page numbers for each condensed entry are 
sorted into numerical order. 


To illustrate, here is an example list of eight items, as displayed 
under option 2, before formatting: 

volts 3 

field 17 

file 6 

volts 2 

file 87 

field 8 

volts 110 

field 3 
After formatting, the above would be condensed as follows: 

field 3,8,17 

file 6,87 

volts 2,3,110 
Option 7: Print index 
This prints hard copy of the complete index on fanfold paper. Extra 
refinements such as form feed and italics can easily be programmed 
to fully utilise the facilities of the particular printer connected. This 


185 


186 


Filing information 


option, in its present form, performs the minimum requirement but 
should work with all printers. If you have one of the smaller printers 
capable of a maximum print width of 40 characters it will be 
necessary to reduce the print WIDTH command in line 1570. You 
may have the problem of double line spacing. The reason is that 
both the computer and the printer perform a carriage return at the 
end of each line. Depending on your printer, the cure is sometimes 
no more than flicking a tiny switch somewhere within the printer 
or, in other cases, by sending a suitable set of control characters. In 
the last resort, pin 14 of the ribbon interface cable may need open 
circuiting but you should seek professional advice before you start 
hacking away. Needless to say, the official Amstrad printer should 
give correct line spacing without requiring any changes. 


General operating procedure 

It is unlikely that the complete index would be completed in one 
keyboard session so the complete task would entail much saving, 
re-loading, adding more items and modifying etc etc. Formatting 
can be carried out at any time but, if time is precious, leave the 
formatting till last because, with a large index, this could take some 
time. One word of warning — after you key in the listing, make sure 
you thoroughly test your program on all options with a small 
dummy index of, say, twenty items before embarking on a major 
project. As a matter of interest, the program was used to prepare the 
index at the end of this book. 


How Program 7.2 works 


Index entries, whether formatted or not, are stored in RAM as a 
single string within the string array, A$. 

The listing simplifies to a series of main subroutines which may 
call on certain subordinate subroutines. The main subroutines are 
all controlled from one of two straightforward menus via ON 
GOSUB commands. Many of the subordinate subroutines, such as 
Input validation, have been covered in Chapter 3 so need not be 
described again. However, some have been slightly modified to 
perform additional duties. 

For the benefit of standard CPC664 owners, the cassette buffers 
have not been permanently allocated. These lines may be added if 
required (see Chapter 1). 


Create Index (GOSUB 510) 

This subroutine obtains input from the user about the index size and 
title. The index array, A$, is DIMensioned with one extra element. 
This is to allow for certain conditions which arise when option six is 
selected and the index is full. Line 560 gets the index title from the 
user and, if necessary, truncates it to 38 characters by setting limit% 
to 38 prior to the GOSUB 1740 command. Line 580 ensures that at 
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least one entry is made into the index, by calling the add records 
subroutine at line 1080. 


Load index and save index (GOSUB 620 and GOSUB 740 
respectively) 

These subroutines are similar to their analogues in Program 7.1. The 
only difference is that a simple string array is loaded or saved rather 
than a rectangular array. Again, one extra element is added to the 
DIMension command. 


Display index (GOSUB 860) 

The main problem here was to find a method of displaying a 
screenful of index entries having widely different string lengths. 
They may be only a few characters long initially, but after formatting 
they could grow to a maximum of 225 characters and occupy six 
lines of the screen. The solution chosen is to display the first index 
entry by default and then allow other entries to be continuously 
scrolled into view only while the ENTER key is depressed. This 
would allow the whole index to be examined whilst ensuring that 
none of the screen area is wasted. 

Lines 860 to 870 set up two text windows. These, although not 
strictly necessary, do enhance the display to some degree and 
project a slightly upmarket image. The window of text stream zero 
(the index itself) is scrolled leaving a fixed panel at the top of the 
display containing the title and key instructions. When two 
windows are used in this way, the WINDOW SWAP command can 
be used. This alleviates the need to specify text stream numbers for 
certain commands. 

Lines 940 to 1030 are a loop that repeats while the SPACE bar is 
not PRESSED (key number 47). On pressing SPACE, the default text 
window is set in line 1040 prior to RETURN. 

Within the above loop, the string array is displayed in the way 
described above. The name of the displayed index entry, to the left 
of the first comma, is split off by the INSTR and LEFT$ commands in 
lines 950 and 960, and printed in green. The rest of the string to the 
right of the first comma is printed in yellow. Notice the use of the 
PRINT USING command in line 970. It ensures that the rest of the 
string follows on from the first part. A normal PRINT command 
would cause the second part of the string to be printed on a 
new line. The CALL &BBO03 command in line 980, among other 
things, flushes the keyboard buffer. The WHILE/WEND loop in 
lines 990 to 1000 locks up until the SPACE or ENTER keys are 
depressed. Once the entire index has been displayed, line 1020 
allows the display to be repeated again if required. 


Add to Index (GOSUB 1080) 

The entire subroutine is contained within an outer WHILE/WEND 
loop which terminates if the index is either full or free memory is 
reduced to a low level. Within the loop, the item description and 
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page number pairs are obtained from the user until the command 
EXIT is entered, the receipt of which terminates entries and forces a 
RETURN. The index description portion is truncated to forty char- 
acters by setting limit% accordingly. This should be enough for all 
but the most verbose entries. 

Buried within line 1150 is a rather complex piece of string 
manipulation. However, its purpose is simply to strip off the leading 
space that is returned for positive numbers by the STR$ command. 


Modify index item (GOSUB 1210) 

This subroutine is a cut down version of that provided in Pro- 
gram 8.1 and allows direct editing/modification using LINE INPUT. 
The required index item is found via a call to the FIND ITEM 
subroutine (GOSUB 1950) and is displayed via a call to the display 
index item (GOSUB 1660). The modified data is entered, via a call to 
the get line input subroutine (GOSUB 1740). When modifying the 
index title, the variable limit% is set to 38. This ensures any 
modified title is truncated to 38 characters for display purposes. 


Delete index item (GOSUB 1290) 

The required item is found and displayed as above. After confirma- 
tion from the user, the item is deleted and the resulting gap in the 
array closed up by line 1340. 


String Quicksort (GOSUB 1380) 

This is a fairly fast subroutine for sorting a string array and is 
described at length in Chapter 8. However, if more speed is 
required use the machine code quicksort, also described in the same 
chapter. 


Print index (GOSUB 1560) 

This is a simple print routine that prints the index out on fanfold 
paper. The print width is set to 50 in line 1570. The index title is 
printed in line 1580 and the index is printed out by the FOR/NEXT 
loop (lines 1600 to 1620). 


Display index item (GOSUB 1660) 
This prints out a string representing an index entry and is called by 
the Modify and Delete index item subroutines. 


Get Line Input (GOSUB 1740) 

This is a refinement of the version described in Chapter 3. The extra 
features are the rejection of string input containing commas (in line 
1800) when limit% is set to 40. This only occurs when called by the 
Add to index subroutine. In contrast, string input not containing a 
comma is rejected in line 1790 when limit% is set to 255. This occurs 
when called from the modify index item subroutine (GOSUB 1210). 


Find item (GOSUB 1950) 
This is a simple sequential search conducted on the array A$, the 
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search starting at the first item in the array. The flag, flag%, is set to 
one if the item is found and zero if not found. The array index 
pointer, R%, is returned by the subroutine if a match is found. The 
search key is entered by the user into K$ and only enough 
characters to distinguish the item from others need be entered. The 
string comparison is performed in line 2020. 


Format index (GOSUB 2230) 

This subroutine is the heart of the program and is responsible for 
condensing all matching index entries and their corresponding page 
numbers into a single string and closing up the resultant gaps in the 
array. 

The subroutine starts by a call to the sort routine (GOSUB 1380) 
which sorts all the indexed items within the array into alphabetical 
order. Each string in the index is split, in turn (by a GOSUB 2350 
call) into a descriptive part, which we call port$ and a page number part 
called starboards$. The boundary for the split is marked by the first 
encountered comma. R% is the current array pointer and count% is 
the condensed array pointer. These pointers or counters will grow 
further apart as the index is condensed, since may consecutive 
strings, having the same port$, may have been condensed into one 
array element. Within the WHILE/WEND loop (lines 2260 to 2300), 
comparisons of port$ are made between successive pairs of items in 
the index. If they have different port$ values then only the first is 
written to the condensed array. If the same, the duplicated port$ is 
copied into org$ and a call is made to the Condense index sub- 
routine (GOSUB 2410). This loop continues until all the array strings 
have been tested and if necessary condensed. Finally, on exit from 
the loop, the current array length variable, L%, is set to the new 
condensed array length, count%. 


Split string (GOSUB 2350) 

This subroutine splits the string A$(R%) into two substrings, port$ 
and starboard$, as described above. A combination of INSTR, 
LEFT$ and RIGHT$ are used to perform the split. 


Condense index (GOSUB 2410) 

Within the WHILE/WEND loop at lines 2420 to 2460, consecutive 
strings are split and port$ compared to the original duplicated entry 
description, org$. The loop exits when either a new port$ is detected 
or the current array length is exceeded. Within the same loop, a call 
is made to the collect page numbers subroutine (GOSUB 2560). This 
call gathers up the page numbers of duplicated index descriptions 
and places them into an integer array ready for sorting. The page 
number information is obtained from starboard$ each time. Line 
2470 enforces a call to the integer selection sort routine (GOSUB 
2640). This sorts the page numbers into numerical order. Lines 2480 
to 2520 rebuild the condensed string entry from org$ and the sorted 
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page number array, B%. The leading space returned by the STR$ 
function is stripped off during the rebuild in line 2510. 


Collect page numbers (GOSUB 2560) 

This subroutine splits up starboard$ (assigned to K$ in the previous 
subroutine) and assembles page numbers into an integer array. The 
VAL command in line 2570 returns the numerical value of the string 
K$ up to the first non-numerical character (a comma in this case). 
This value is assigned to the current integer array element indexed 
by M%. The INSTR command in line 2580 returns the position of 
the first occurrence of a comma into F%. Line 2590 chops off the 
leading comma from K$ ready for the next cycle of the loop. Line 
2600 continues stocking the integer array. B%, until no more 
commas are present in K$. This condition is detected when F% is set 
to zero by the INSTR command in line 2580. 


Integer selection sort (GOSUB 2640) 
This sorts into numerical order the temporary integer array, B% 
stocked with page numbers. The mechanism, like that for the 
quicksort, is described in Chapter 8. 


Summary 


1 User-friendly filing systems should include ‘Are you sure?’ 
questions where a mistaken entry could erase important data. 

2 A data file can only be accessed from within a resident program. 
3 Arecord contains all information on one complete entity in a file. 
4 A field contains one item of information in a record. 

5 Field width is the maximum number of characters allowed 
within the field. 

6 The keyfield is that field used to uniquely identify the record 
within the file. No two records must have the same keyfield. 

7 If the entire file must be resident in RAM before a record can be 
accessed, it is said to be RAM based. 

8 Store based files can remain on disc and only the chosen record, 
or few records, need occupy RAM space. 

9 Only RAM based files are practical with cassette storage. 

10 Data files cannot be stored or loaded back by using SAVE and 
LOAD commands. 

11 Before data files can be accessed, an appropriate OPENOUT or 
OPENIN command is required. 

12 The command CLOSE must be used after you have finished 
with a data file. 

13. The command PRINT #9 or WRITE #9 writes on tape instead 
of the screen. 

14 INPUT #9 inputs from tape instead of from the keyboard. 

15 The Primary menu in Program 7.1 is for initially creating or 
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loading an existing file whereas the Main and Subfile menus 
provide various processing options for the main and _ subfiles 
respectively. 

16 A subfile contains those records selected from the main file 
which satisfy some search criteria. 

17 To save wasting another array, the records chosen for the sub- 
file are repositioned at the top of the main file. 

18 Program 7.2 allows an index to be prepared in a piecemeal 
fashion but finally processes the result into conventional index page 
format — all page numbers referring to the same item on the same 
line, separated by commas. 
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Introduction 


Computers engaged on serious work spend a large proportion of 
processing time in the sorting or ordering of data. Consequently, 
over the last three decades, much thought has been devoted to the 
subject. We now have a vast selection of algorithms to choose from. 
Which one is used for a particular application depends on many 
factors such as worst case execution speed, memory usage and 
programming effort. To some the subject of sorting is dry, un- 
interesting and boring. To others it may be an interesting pastime in 
which hours are spent in an attempt to tweak a few extra milli- 
seconds from a sort time. However you view the subject, it is 
generally agreed that a good knowledge of sorting methods is 
essential to anyone remotely interested in serious computing. In 
this chapter we can only cover a few of the more popular al- 
gorithms. However, if the subject appeals to you there are quite a 
few monumental tomes to wade through at your local university 
bookshop in which case this chapter should serve as an introductory 
primer. 

Searching and sorting is a difficult subject which can involve a lot 
of dry mathematics. We shall rely on a blend of simple arithmetic 
together with plain descriptions and advice on the use of the various 
algorithms. In doing so, we have to depart from the standard format 
used in previous chapters for presenting subroutines because the 
part used for testing is universal to a group of subroutines. We 
begin with a simple Exchange sort and progress finally to a machine 
code version of the Quicksort which is capable of handling two- 
dimensional string arrays. 

The latter is capable of sorting a thousand strings in less than two 
seconds. Finally, we cover a pair of algorithms for searching con- 
tinuous lists (arrays), the simple sequential search and the more 
efficient binary search. 


Sorting string arrays 
The BASIC sort subroutines in this chapter are given line numbers 
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starting at 10000 and each can be tested using one of four test 
programs provided. Program 8.1 tests all the single dimensional 
string array sorts written in BASIC. Lines 30 to 70 obtain the array 
size and DIMension it accordingly. Lines 80 to 180 fill the array with 
randomly generated strings of various length and print them out to 
show the original order. The variable, START, is set to the starting 
time (in seconds) in line 220. The GOSUB at line 230 initialises 
sorting, assuming of course that a subroutine starting at line 10000 
is present. On return from the subroutine, line 240 calculates the 
execution time (in seconds) and sets the variable T accordingly. 
Lines 250 to 320 display the sorted array and the sorting time. 


Program 8.1 Testing program for BASIC string array sort 
routines 


10 REM UNIVERSAL TEST PROGRAM FOR 
20 REM BASIC STRING ARRAY SORTING 
30 CLS 

40 INPUT"Sort how many strings"; NUMBERZ 
50 PRINT 

60 REM FILL AND DISPLAY RANDOM ARRAY 
70 DIM AS (NUMBERZ) 

80 FOR RZ~=1 TO NUMBERZ 

90 BS="" 

100 AZ=6*RND+1 

110 FOR Z%=1 TO AZ 

120 NZ=25*#RND 

130 K$=CHR$ (NZ+65) 

140 BS=BS+KS 

150 NEXT 

160 A¥#(RZ) =BS 

170 PRINT AS(RZ) 

180 NEXT 

190 PRINT: PRINT 

200 PRINT"SORTING ARRAY" 

210 PRINT: PRINT 

220 START=TIME/300 

230 GOSUB 10000 

240 T=TIME/300-START 

250 FOR RZ=1 TO NUMBERZ 

260 PRINT AS (RZ) 

270 NEXT 

280 PRINT 

290 PRINT"RECORDS SORTED="5; NUMBERZ 
300 PRINT 

310 PRINT"SORTING TIME="3;ROUND(T,2); "SECONDS" 
320 END 
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Although we have concentrated on sorting string arrays, they can 
easily be converted to sort floating point or integer arrays by 
changing all string variable references to either of the above variable 
types. The timing tables provided are a general guide to the 
performance to be expected for the various algorithms. They are all 
based on the sorting of a randomly generated array of strings. The 
times given are typical and may vary depending on the particular 
strings generated. 


The exchange sort 


This is a simple sorting method but rather slow. The algorithm 
employed in Subroutine 8.1 is based on comparison of adjacent 
items in a string array. The object is to sort the array A$ into 
ascending order. A pass, starting at A$(1), is made through the 
array until two adjacent elements are found in descending order. 
The offending array elements are exchanged in position and the 
cycle restarted at A$(1). The cycle is repeated as many times as 
necessary until the list is completely ordered. The technique, 
although inefficient, is as good a place to start as any. Its merit lies in 
its simplicity. 


9999 REM EXCHANGE SORT SUBROUTINE 
10000 NZ=0 

10010 WHILE NZ<NUMBERZ-1 

10020 NZ=NZ+1 


10030 IF A%(NZ) >AS(NZ+1) THEN T$=A$ (NZ) 2 AS (NZ) =AS ( 
NZ+1) 2 AS (NZ+1) =T$:NZ=0 

10040 WEND 

10050 RETURN 





Table 8.1 shows typical execution times. 


Table 8.1 Typical Exchange sort times 


Random strings Sorting time (sec) 


20 8.6 
50 142.9 





Table 8.1 shows that the sorting time increases alarmingly as the 
array size increases. The worst case number of comparisons needed 
when the array is reverse ordered is given approximately by (N*3)/ 
6, providing N is large. 


The bubble sort 


The bubble sort is an improvement on the exchange sort because 
time is not wasted comparing adjacent array elements already 
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correctly positioned. This is probably the most often used sorting 
routine providing there is only a small number of array elements. A 
bubble sort demonstration is given in Subroutine 8.2 


Subroutine 8.2 


9999 REM BUBBLE SORT SUBROUTINE 
10000 SIZEZ=NUMBERZ 

10010 WHILE SIZE%>1 

10020 SIZEZ=SIZEZ%-1 

10030 FOR NZ=1 TO SIZEZ 


10040 IF A#(NZ) >AS(NZ+1) THEN T#=AS (NZ) 2 AS (NZ) =AS ( 
NZ+1) AS (NZ+1) =TS 

10050 NEXT 

10060 WEND 

10070 RETURN 





Subroutine 8.2 consists of an inner and an outer control loop. The 
pairs of array elements are repeatedly incremented, compared and, 
if necessary, swopped in position within the inner loop. The 
maximum value string in the array bubbles through to the last 
position. It is no longer necessary to involve this string in further 
comparisons, since it will be in its final array position. The outer 
loop counter, SIZE% can thus be decremented by one. On the fol- 
lowing series of inner loop cycles, the next largest value string 
bubbles through to the next to last position in the array, and so on, 
until the array is completely ordered. 

Table 8.2 shows the timing data for the string bubble sort 
program. 


Table 8.2 Typical Bubble sort times 
Random strings Sorting time (sec) 
20 1.7 





50 10.8 
100 42.1 





Study of Table 8.2 reveals that the bubble sort is an improvement 
on the exchange sort in terms of execution speed. The average 
number of comparisons is given approximately by (N*2)/2, where 
N is the number of array elements. Thus it will take four times as 
long to sort double the number of elements. The bubble sort would 
be used to sort small lists, of say, less than 20 items. It is a short 
routine, easy to type in and occupies little memory. 


The Insertion sort 


The Insertion sort would seem to us the most natural sorting 
method of all. This is probably the most widely used method 
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adopted for sorting a hand of cards at a whist or bridge game. In 
essence, all we do is extract an offending card and insert it as close 
as we can to its final position. A gap for its insertion is effected by 
moving all trailing cards one position to the right. This is repeated a 
number of times until the hand is entirely sorted. 

The principle is much the same when sorting a string array. We 
start off with the first string element, which is considered the initial 
sorted list (a list containing one item is already sorted). The length of 
the sorted list is subsequently increased by one each time an 
insertion is made. 

The process starts by extracting the first currently unsorted item 
into an arbitrary variable. A search of the sorted list is then 
conducted for the correct insertion position. For increased effi- 
ciency, the list is searched from its tail toward its head so strings can 
be moved one position down the array at the same time. This 
ensures that a free slot will be available at the correct insertion point. 
This process is repeated until the entire array is sorted. 


Subroutine 8.3 


9999 REM INSERTION SORT SUBROUTINE 
10000 A#(O)="" FOR IZ=2 TO NUMBER% 
10010 WHILE A#(1Z)<AS(IZ-1) 

10020 JZ=1%: T$=AS(1%) 

10030 WHILE A#(JZ%-1) >TS 

10040 J%Z=J7%-1 


10050 A#(J%+1) =AS (IZ) 
10060 WEND 

10070 AS(JZ) =T# 
10080 WEND 

10090 NEXT 

10100 RETURN 





The Insertion sort is listed as Subroutine 8.3 and can be tested 
with Program 8.1. Since a single item is already sorted, we start with 
the second item in the array. Line 10010 checks if the current item 
A$(I%) is in the correct place already. If not it is pulled out into T$. 
Lines 10030 to 10060 shift items one position down the sorted list 
until the correct insertion point, marked by J%, is found for T$. Line 
10070 performs the actual insertion. All loops terminate when the 
last array item is correctly inserted. In order for the algorithm to 
work in all cases it is important that the A$(0) element is set to a null 
string, otherwise the WHILE/WEND search loop (line 10030) may 
not terminate correctly in the case where T$ belongs at the head of 
the array. When sorting real or integer arrays then the zeroth array 
element should be initialised to the maximum allowable negative 
number for the array type. A universal, but slower, alternative is to 
add the following line: 


10055 IF J%=1 THEN 10070 
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Table 8.3 Typical Insertion sort times 


Random strings Sorting time (sec) 





Table 8.3 shows that Insertion sort is approximately 100% faster 
than the bubble sort for random string arrays on the Amstrad 
CPC464/664. The number of comparisons is approximately given by 
(N*2)/4. However, when the array is already in order, or nearly so, 
the performance is far superior to that of the bubble sort. The 
algorithm can be further improved by employing a binary search, 
rather than a simple sequential search, but it is doubtful if the extra 
complication is worth the trouble. 

The Insertion sort would be used in situations similar to that in 
which a bubble sort would be used. In addition, it is ideal where a 
single item is to be sorted into a previously ordered list. Again it is 
short, easy to type in and uses little memory. 


The Selection sort 


The main disadvantage of the Insertion sort is that items are moved 
in the array only one position at a time. Ata late stage in the sort this 
will result in many items in the sorted list needing to be moved in 
order to make an insertion. Selection sort overcomes this ineffi- 
ciency by immediately moving each string element to its final 
position in the array. 

Subroutine 8.4 consists of an inner and an outer loop. On each 
inner loop pass, the largest string (ASCII wise) is selected and 
exchanged immediately with the last item in the array. The outer 
loop count is decremented by one and the process repeated on the 
reduced list. The array thus becomes ordered progressively from the 
tail towards the head as each inner loop is completed. 


Subroutine 8.4 


9999 REM SELECTION SORT SUBROUTINE 
10000 FOR IZ=NUMBERZ% TO 2 STEP -1 
10010 MZ=1 

10030 FOR J%Z=2 TO 1% 

10040 IF A$(JZ) >AS(MZ) THEN MZ=J3% 


10050 NEXT 

10060 T$=A$ (MZ) : AS (MZ) =AS (IZ) SAS (IZ) =TE 
10070 NEXT 

10080 RETURN 
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Line 1000 is the outer FOR/NEXT loop which counts from the tail of 
the array toward the head. The inner FOR/NEXT loop at line 10020 
selects the largest value string each time. Line 10050 performs the 
actual exchange. It is worth mentioning at this point that the 
Amstrad CPC464/664 does not swop the strings themselves. It 
simply swops pointers in an access table; thus only three bytes are 
exchanged each time irrespective of the size of the string. 


Table 8.4 Typical Selection sort times 


Random strings Sorting time (sec) 





Table 8.4 shows only a slight improvement in performance for 
large random arrays over the Insertion sort. The number of com- 
parisons when N is large is approximately (N*2)/2 but it sorts with a 
greatly reduced number of exchanges. The algorithm is very short 
and consumes a minimum of memory space and for this reason is 
popular. Due to its low exchange count, it is the ideal choice for the 
simple but relatively efficient sorting of two dimensional arrays (see 
Subroutine 8.7). The decision whether to use Insertion sort or 
Selection sort also depends on the particular micro. Some machines 
may perform exchanges and/or string comparisons slower than 
others, so the above results are not universal. 


The Shell or Diminishing Increment sort 


This group of sort algorithms, sometimes named after D. L. Shell 
who devised his Shellsort in 1959, produce a significant leap in 
overall performance. There are numerous minor differences but 
only one such variation will be dealt with in this chapter. The 
previous sort routines are efficient for handling small string arrays, 
but perform badly on large arrays. Try running Subroutine 8.2 with 
1000 strings. Many hours will elapse before the sort is completed. 
An improvement, where large numbers of elements are involved, is 
to use a Shell sort of which Subroutine 8.5 is an example. 

The execution speeds of the previous subroutines are limited by 
the need to compare only adjacent array elements. This means that 
elements, other than for the Selection sort, can only be moved by 
one array position at a time. The diminishing increment sort is an 
attempt to overcome this problem by making the initial comparisons 
on elements which are positioned far apart from each other. The sort 
process begins by making comparisons and insertions over this 
large increment. Subsequently, elements closer together are sorted 
as the increment is progressively reduced at each sorting pass. An 
important proviso is that the final sorting pass must be performed 
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with an increment of one. The earlier passes move the elements 
closer to their final array positions. The final pass, which performs 
an ordinary insertion sort with an increment of one, executes very 
quickly since the array is already roughly ordered. Notice that the 
portion buried within the Shellsort (lines 10040 to 10140) is virtually 
identical to that of the insertion sort of Subroutine 8.3. However, 
there are versions of Shellsort around that employ other sorting 
methods on the subsets produced at various increments. 

The best way to understand the Shell sort, or indeed any other 
algorithm, is to utilise a trace table. The idea is to follow the program 
through on paper, using arbitrary test data and taking notes of 
various key variables such as loop counters etc. This can often be 
more instructive than reading dreary program breakdowns which 
can obscure the essential details. 


Subroutine 8.5 


9999 REM SHELL SORT SUBROUTINE 
10000 INCZ=NUMBERZ 

10010 WHILE INCZ>1 

10020 INCZ=INCZN\3S+1 

10030 FOR STARTZ=1 TO INCZ% 
10040 FOR IZ=STARTZ+INCZ TO NUMBERZ STEP INCZ% 
10050 WHILE A#(1Z)<AS(IZ-INCZ) 
10060 JZ=12%: T$=AS (17%) 

10070 WHILE A$(JZ-INCZ) >TS 
10080 A#(J%) =AS$(JZ-INCZ) 

10090 J%Z=JZ-INCZ 

10100 IF JZ=START% THEN 10120 
10110 WEND 

10120 A%(JZ) =T$ 

10130 WEND 

10140 NEXT 

10150 NEXT 

10140 WEND 

10170 RETURN 


The timings for the Shellsort are given in Table 8.5. Notice the 
increase in execution speed over previous algorithms. 


Table 8.5 Typical Increment sort times 


String array size Sorting time (sec) 





The choice of increments is purely arbitrary as long as the final 
increment is 1. Other values of increment may work equally well, 
worse or even better. Analysis of Shellsort is said to be very difficult 
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and estimates of the number of comparisons required have only, to 
date, been estimated under special conditions. Nevertheless, Shell- 
sort is significantly faster under most conditions than any of the 
preceding algorithms. 

This particular version is quite acceptable written in BASIC 
provided N is not too large. Please note that the division sign in line 
10020 is integer division not normal division. 


The Quicksort 


The Quicksort algorithm devised and named by C. A. R. Hoare in 
1962 is one of the fastest known for sorting large random arrays 
and can approach the theoretical minimum sorting time propor- 
tional to log n. This algorithm often impresses due to its speed when 
sorting large numbers of random elements. 

The fundamental idea behind Quicksort is the divide and conquer 
technique so beloved by politicians. We noted earlier that sorting 
small lists is far more efficient than sorting large lists. It follows, that 
if we split an array into two sublists containing different groups of 
strings and sort each list separately, we save a lot of comparisons 
and, therefore, sorting time. To do this, we estimate an array 
element that, hopefully, will have a median value and call this the 
pivot. All strings having a value less than the pivot (ASCII wise) will 
be placed above it in the lower half of the array and all strings 
having greater value than the pivot placed in the higher half. If 
these two portions of the array are sorted separately, either side of 
the pivot, then the array will be completely sorted. The estimate of 
the pivot value is all important here. For instance, we could choose 
the first array element or the last array element in a random array. 
However, if the list is partially sorted, as may occur in practice, the 
performance may be seriously degraded because the pivot will be 
too far offset from the median value to make the split worthwhile. 
This effect can be reduced statistically by choosing the pivot as the 
mid point element of the array. There are, of course, many other ways 
of obtaining the pivot but we will employ this method. Incidentally, 
during worst case conditions, where the above effect is dominant, 
the sorting time can be as poor as that for a bubble sort (approxi- 
mately proportional to N’) but this is unlikely to happen in practice. 

One method of implementing Quicksort is to keep partitioning 
lists in this way till we have many lists containing, say, 15 elements 
at most and then selection sorting them. Alternatively, if we carry 
on and take this partitioning process to its limit then each sublist 
will eventually contain only one element. In this case there will be 
no need to employ a selection sort at all. 

The Amstrad CPC464/664 BASIC supports only limited recursive 
techniques. For instance, it cannot store local variables generated 
during the recursion, therefore we need to set up a stack to store the 
limits of lists that have not yet been sorted. (A stack is a section of 


The Quicksort 


memory where the last variable value stored is the first recalled). 
The array index limits of the lower sublist are lowhead% and 
lowtail% and highhead% and hightail% for the sublist. The head 
and tail parameters of the sublists yet to be sorted are put on the 
stack. Thus, if we are presently sorting the array between A$(low- 
head%) and A§$(lowtail%) then highhead% and hightail% would be 
placed on the stack so the sublist A$(highhead%) to A$(hightail%) 
could be sorted later. It transpires that it is better to put the longer 
sublist limits on the stack and process the shorter sublist im- 
mediately. This is the task performed in line 10100. Each time a list is 
further partitioned in the outer WHILE/WEND loop, the process is 
repeated. On exit from the loop in line 10120, the sublists, whose 
parameters were placed on the stack, are taken in sequence (last in, 
first out) and sorted in a similar manner. 

It is often stated that Quicksort uses a lot of memory because the 
program listing is longer, it uses more variables and needs to 
employ a fixed stack area of memory. However, the extra memory 
used by the stack itself is not excessive. The number of stack levels 
needed by Quicksort is given by LOG,(N). Therefore, to sort say 
4,096 strings, the number of stack levels needed will be LOG2(4096) 
=12. In Subroutine 8.6 we need two stacks, consisting of at least 12 
integer array elements each, making a total of 24. Each array 
element DIMensioned consumes 2 bytes, so 48 bytes of array space 
will be claimed. This memory need not be permanently allocated 
since we can DIMension the stack at the start of the subroutine (line 
10000) and ERASE it at line 10130. This frees the memory again for 
use by the main program. 

Table 8.6 reveals that, over the range tested, there is an approxi- 
mately linear relationship between the execution time and the 
number of elements sorted. Quicksort is used wherever large 
numbers of random strings need to be sorted. 


Subroutine 8.6 


9999 REM STRING QUICKSORT SUBROUTINE 
10000 DIM stack1%(16) ,stack2Z(16) 
10010 sp%=0:headZ=1: tail Z=NUMBERZ 
10020 WHILE headZ%<tailZ% 

10030 pivot$=A$ ( (head%~+tailZ) \2) 

10040 a%=head%Z:bZ%=tailZ% 

10050 WHILE A#(a%)<pivot$: aZ=aZ%Z+1:WEND 


10060 WHILE A#(b%) >pivot#: b%=b%~-1: WEND 

10070 IF a%<b% THEN t$=A¥ (aZ%) : AS (aZ) =AS (bX) AS (DZ) 
=t$:aZ=a%Z+12b%=b%-1:GOTO 10050 

10080 IF a%=b% THEN lowtail%=b%-1:highheadZ=aZ%Z+1 E 
LSE lowtail%Z=b%: highheadZ=aZ 

10090 sp%=sp%+1: lowheadZ=headZ:hightailZ=tail% 
10100 IF lowtailZ—-lowheadZ%<hightail%—-highhead% THE 
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N stack1i%(sp%) =highheadZ: stack2%(spZ) =hightailZ%:he 
adZ=1 owhead%: tailZ=lowtailZ ELSE stack12%(sp%)=lowh 
eadZ%: stack2%(s9%Z) =lowtail%Z:head“Z=hi ghhead%: tail%=h 
ightailZ% 


10110 WEND 

10120 IF sp%>0 THEN headZ=stack1%(spZ%) stailZ=stack 
22(sp%) :spZ=sp%Z-1:GOTO 10020 

10130 ERASE stack1%,stack2% 

10140 RETURN 





Table 8.6 Quicksort times 


String array size Sorting time (sec) 





It is generally agreed that there is no universally superior sorting 
algorithm. Each have their relative advantages and disadvantages. 
The programmer should choose the one most suited to the particu- 
lar task in hand taking into account such things as number of items 
to be sorted, available memory, acceptable execution time, and not 
least, programming effort. It is pointless to use an elaborate sorting 
routine, such as Quicksort, to sort a list of say twenty items. It is 
equally pointless to employ one to sort a fairly large list once only. 


Sorting rectangular string arrays 


A file organisation, commonly encountered in RAM based filing 
systems, is the two-dimensional or rectangular string array. If a RAM 
based file is DIMensioned A$(FIELDS%,RECORDS%) then the file 
A$ can be considered to contain RECORDS% records each of 
FIELDS% fields. We can define any field in a specific record by 
A$(F%,R%) where F% is the field number and R% is the record 
number. 

If records are to be sorted according to a specific field, we need to 
modify our routines to exchange all fields of the record pairs each time. 
An extra FOR/NEXT loop will be needed to take care of this. 

Figure 8.1 shows how to visualise such a file in memory. The 
following points should be noted: 


1 When BASIC DIMensions a rectangular array, 3 byte string 
descriptors are reserved for each array element whether they are 
used or not. Unfortunately, this includes all zero indexed elements. 
In order to maximise the use of available memory we should ensure 
that field zero is used as one of the legitimate fields. If we do this then 
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Figure 8.1 
Field 1 Field 2 


Field headings 
Record 1 
Record 2 


Record 3 
Record 4 
Record 5 
Record n 


we can DIMension, say, a 400 record, 5 field file as A$(4,400) rather 
than A$(5,400) which may, at first sight, seem an obvious choice. 
Neglect of this point could waste 400*3=1200 bytes of memory 
unnecessarily. 

2 The record zero elements are not wasted since they are con- 
venient for storing the field headings themselves. 


Sorting by numeric fields 

If a string sort is to be used successfully on numeric data fields 
stored in string form, the user should ensure that all entries have a 
constant number of digits (including leading zeros). An alternative 
is the conditional use of the VAL statement. However, this would 
introduce further complication along with an alarming increase in 
execution time. 


Test program for rectangular string array sorting 


To test subroutines that can sort two dimensional string arrays we 
need to modify our testing program. Program 8.2 is the modified 
test program. The listing is generally similar to Program 8.1 but 
instead DIMensions, sets up and displays a random two dimen- 
sional string array. The array should be pictured as a number of 
fixed, three-field, randomly generated records. The particular sort- 
ing subroutine on test is expected to be entered from line 10000 
onwards. 


Program 8.2 


REM UNIVERSAL TEST PROGRAM FOR BASIC 

REM RECTANGULAR STRING ARRAY SORTING 

CLS 

INPUT"Sort how many 3 field records";RECORDSZ 


FIELDS%=2:REM fields 0,1,2 

INPUT"Sort which field (0-2) ";FIELDNUM% 
PRINT 

REM FILL AND DISPLAY RANDOM ARRAY 
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90 DIM AS(FIELDSZ,RECORDSZ) 
100 FOR RZ=1 TO RECORDS~ 
110 FOR F2Z=0 TO FIELDSZ% 
120 BS="" 

130 A%Z=6*#RND+1 

140 FOR Z%Z=1 TO AZ 

150 NZ=25*RND 

160 K#=CHR$ (NZ+65) 

170 BS=BS+KsS 

180 NEXT 

190 AS(FZ,RZ) =BS 

200 PRINT AS(FZ,RZ%), 

210 NEXT 

220 NEXT 

230 PRINT:PRINT 

240 PRINT"SORTING ARRAY" 
250 PRINT:PRINT 

260 START=TIME/300 

270 GOSUB 10000 

280 T=TIME/300-START 

290 FOR RZ=1 TO RECORDS% 
300 FOR F%~=0 TO FIELDSZ 
310 PRINT A#(FZ,RZ), 

320 NEXT 

330 NEXT 

340 PRINT 

350 PRINT"RECORDS SORTED=";RECORDSZ 
360 PRINT 

370 PRINT"SORTING TIME=";ROUND(T,2); "SECONDS" 
380 END 














Selection sort (Rectangular string array) 


When sorting rectangular arrays we need to move not just one 
string element each time but all the elements in one dimension. If each 
string in a twenty field array is accessed by a three byte string 
descriptor and we exchange them through an intermediate variable 
then 3*3%*20=180 bytes need to be moved on each record ex- 
change. If we require efficient sorting then we should choose an 
algorithm that performs as few exchanges as possible. The number 
of string comparisons, although important, is of lower priority. The 
Selection sort is probably the most efficient of the simpler al- 
gorithms for sorting two dimensional arrays. This is due to the low 
number of exchanges performed. Subroutine 8.7 shows how the 
Selection sort is modified for sorting a rectangular string array. An 
examination of Table 8.7 reveals that Subroutine 8.7 can sort a two 
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dimensional array faster than a bubble can sort a single dimensional 
string array (see Table 8.2). 


Table 8.7 Typical execution times for Subroutine 8.7 


Records Sorting time (sec) 





Subroutine 8.7 


9998 REM SELECTION SORT SUBROUTINE 

9999 REM RECTANGULAR STRING ARRAY 

10000 FOR I%=RECORDS% TO 2 STEP -1 

10010 MZ=1 

10020 FOR J%=2 TO 1% 

10030 IF AS(FIELDNUMZ,J%Z) >AS(FIELDNUMZ,MZ) THEN MZ 
=J% 

10040 NEXT 

10050 FOR F%=0 TO FIELDS% 

10060 T#=A$(F2Z,MZ) SAS (FA,MZ) =AS (FZ, 1K) sAS( FA, 1%) =T 
$ 

10070 NEXT 

10080 NEXT 

10090 RETURN 


Shellsort and Quicksort versions 


Rectangular string array versions of Shellsort and Quicksort are 
given in Subroutines 8.8 and Subroutine 8.9 respectively. The 
associated timing is shown in Table 8.8 and Table 8.9. 

Subroutine 8.9 was used in the index processor described in the 
previous chapter. 


Table 8.8 Typical execution times for Subroutine 8.8 


Records Sorting time (sec) 





Subroutine 8.8 


9998 REM SHELL SORT SUBROUTINE 
9999 REM RECTANGULAR STRING ARRAY 


10000 DIM TS#(FIELDSZ) 
10010 INCZ=RECORDSZ 
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10020 WHILE INCZ>1 

10030 INCZ=INCZN3+1 

10040 FOR STARTZ=1 TO INCZ% 

10050 FOR IZ%=STARTZ+INCZ%Z TO RECORDSZ STEP INC% 
10060 WHILE A#(FIELDNUMZ,1Z) <A (FIELDNUMZ, I%Z-INCZ) 
10070 RZ=I%Z:FOR F2Z=0 TO FIELDSZ: T$ (FZ) =AS(FZ%,1%) 2 N 
EXT 


10080 WHILE AS(FIELDNUMZ,RZ-INCZ) >T# (FIELDNUMZ) 
10090 FOR F%=0 TO FIELDS“: A$(FZ,RZ) =AS(FXZ,RZ-INCZ) 
s NEXT 

10100 RZ=RZ-INCZ 

10110 IF RZ=STARTZ THEN 10130 

10120 WEND 

10130 FOR F%=0 TO FIELDSZ: AS(FZ,RZ) =TS$ (FZ) NEXT 
10140 WEND 

10150 NEXT 

10160 NEXT 

10170 WEND 

10180 ERASE TS 

10190 RETURN 











Table 8.9 Typical execution times for Subroutine 8.9 











Records Sorting time (sec) 








100 15.5 
200 33.4 
300 144.9 
500 596.5 





Subroutine 8.9 
















9998 REM QUICKSORT SUBROUTINE 
9999 REM RECTANGULAR STRING ARRAY 

10000 DIM stack1%(16) ,stack2%Z (16) 

10010 spZ%=0: head%=1: tail Z=RECORDSZ 

10020 WHILE headZ%<tailZ% 

10030 pivot$=A$% (FIELDNUMZ, (head%+tail%) \2) 

10040 aZ%=head“Z:b%Z=tail% 

10050 WHILE A#(FIELDNUMZ,aZ) <pivot#: aZ=a%+1:WEND 
10060 WHILE AS (FIELDNUMZ,b~Z) >pivot$:b%=b%—-1: WEND 
10070 IF a%<b% THEN FOR CZ=0 TO FIELDS“: t$=A$(CZ,a 
%) sAS(CZ,a%) =AS(CZ%,bZ) SAS(CZ, BDZ) =t$:s NEXT: aZ=aZ%+1ib 
%=bz%-1:GOTO 10050 

10080 IF aZ=bZ% THEN lowtail%Z=bZ-1:highhead%=a%Z+1 E 
LSE lowtail%Z=b2Z:highhead%Z=aZ 

10090 sp%=sp2%+1: lowhead%Z=headZ:hightailZ=tailZ% 
10100 IF lowtail%—-lowhead%<hightailZ—-hi ghhead% 
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N stack1%(sp%) =highheadZ: stack2%(spZ) =hightailZ:he 
ad%Z=1 owhead”%: tailZ=lowtail%Z% ELSE stack1%(sp%)=lowh 
ead’: stack2Z (spZ) =lowtail%:head%=hi ghhead%: tail %Z=h 
ightailZ% 


10110 WEND 

10120 IF sp%>0 THEN headZ%=stack1Z(sp%) :tailZ=stack 
2%(sp%):sp%Z=spz%-1:GOTO 10020 

10130 ERASE stack1%,stack2% 

10140 RETURN 


Other than tweaking the algorithms for slightly better efficiency, 
the results of Table 8.8 and 8.9 are about the best we can expect 
using string sort routines written in BASIC. For further increases in 
execution speed we must resort to Z80 machine code. 


Machine code solutions 


Whatever sort technique we use, there is no denying that where 
large numbers of elements are involved, the execution time can be 
unacceptably high. We are, after all, up against the inherent defects 
of the BASIC language. It is an interpretive, rather than a compiled 
language so execution speed is likely to be slow. 

Even in machine code, it will still be important to select a suitable 
algorithm. For example, assuming a list is large, a bubble sort 
written in machine code wouldn’t execute all that much faster than 
Shellsort written in BASIC. 

Although the details of Z80 machine code programming are 
outside the scope of this volume it would be a pity if we neglected to 
include a few powerful routines for sorting string arrays. However, 
those with a knowledge of Z80 machine code may appreciate the 
remarks on the source code listings. The treatment in the rest of this 
Chapter will concern the preparation and use of machine code 
subroutines rather than the coding details. 


Choosing an algorithm 


Of all the algorithms we have treated in this chapter the Quicksort 
algorithm, in spite of an occasional poor performance noted earlier, 
stands out as being the best overall performer for large arrays. A 
machine code version that is called from BASIC would provide a 
very powerful addition to any CPC464/664 subroutine library. We 
have developed two machine code Quicksorts, one for string arrays 
and one for rectangular string arrays. 

All the assembly language listings in this section have been 
developed using the ‘HiSoft DEVPAC Editor, Assembler, Dissas- 
sembler & Monitor’ (AMSOFT 116) available on tape or disc. Do not 
worry if you have no assembler because hex loading programs, 
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written in BASIC, are provided so that machine code bytes can be 
loaded directly into a fixed area of memory from BASIC DATA 
statements. This memory area can then be saved to tape as a binary 
file. 


Machine code string array sort 


When a string array is DIMensioned by the BASIC interpreter, an 
access table is set up containing three bytes for each string element. 
These bytes are not the strings themselves but the string length and 
address of where they are stored. These three bytes are referred to as 
String Descriptors and represent the string length, low byte address and 
hi byte address respectively. The string length byte is the lowest in 
memory. The actual string, consisting of the ASCII codes in 
sequential memory locations, is stored from the starting address 
given in bytes 2 and 3 above. A string array is thus formed by a 
series of such string descriptors stored sequentially in memory. 
Swopping strings during a string sort is not as difficult as it may first 
appear. We can leave the strings themselves where they are in 
memory and swop the string descriptors, since these tell the BASIC 
interpreter where the string are stored. 

Listing 8.1 is an assembly code (source code) listing based on the 
Quicksort algorithm. The final machine code (object code), neces- 
sary to sort string arrays, is assembled from this and placed into 
memory from address &9900 onwards. 

A suitable test is provided by Program 8.3. It loads the machine 
code binary file from tape or disc, sets up a random string array, 
calls the machine code routine and displays the sorted array. 
Finally, icr those without an assembler, a Hex loading program is 
given iu the form of Listing 8.2. 


Listing 8.1 


3; QUICKSORT 

3;0F A STRING ARRAY 
begin: EQU #9900 

top: EQU begin+#200 
tail: EQU top 

head: EQU topt2 
array: EQU topt+4 


plen: EQU top+d 
slen: EQU top+7 
string: EQU top+8s 
ppoint: EQU topti0O 
lowhead: EQU 
lowtail: EQuU 
highhead: EQU 





Listing 8.1 








































hightail: EQu top+18 


1460 sdipoints EQU top+20 
170 sd2point: EQu topt+22 
180 stackcount: EQU top+24 
190 psdpoint: EQu topt+25 
200 ORG begin 


210 ;Pick up base address of array 
220 ;string descriptors: (array) 


230 LD L, (IX) 

240 LD H, (IX+1) 

250 LD (array) ,HL 

260 ;Pick up tail of array: (tail) 
270 LD L, (IX+2) 

280 LD H, (IX+3) 

290 LD (tail) ,HL 

300 ;Pick up head of array: (head) 
310 LD L, (IX+4) 

320 LD H, (IX+5) 

330 LD (head) ,HL 

340 ;Set stackcounter to zero 

350 SUB A 

360 LD (stackcount) ,A 


370 ;Branch to bypass if head>=tail 
380 loop: LD HL, (head) 


390 LD DE, (tail) 

400 AND A 

410 SBC HL,DE 

420 JP NC ,bypass 

430 ;Initialise highhead and lowtail 
440 LD IX, (head) 

450 LD IY, (tail) 


460 ;Calculate pivot string 
470 ;descriptor address : (psdpoint) 


480 LD HL, (head) 
490 LD DE, (tail) 
500 ADD HL,DE 

510 SRL H 

520 RR L 

530 LD D,H 

540 LD E,L 

550 ADD HL,HL 

560 ADD HL,DE 

570 LD BC, (array) 
580 ADD HL,BC 

590 LD (psdpoint) ,HL 


3Get length and address of 
spivot string : (plen) & (ppoint) 
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620 LD 
630 LD 
640 INC 
650 LD 
6460 LD 
670 INC 
680 LD 
690 LD 





700 ;Set pointer 
710 ;descriptor: 


























720 LD 
730 LD 
740 ADD 
750 ADD 
760 ADD 
770 LD 


780 ;Set pointer 
790 ;descriptor: 


800 LD 
810 LD 
820 ADD 
830 ADD 
840 ADD 
850 LD 


860 ;Get length 


880 first: LD 





890 LD 
900 LD 
910 INC 
920 LD 
930 LD 
940 INC 
950 LD 
960 LD 














990 LD 
1000 LD 
1010 LD 
1020 comp: LD 
1030 cP 
1040 JR 
1050 JR 
1060 INC 
1070 LD 








A, (HL) 
(plen) ,A 

HL 

A, (HL) 
(ppoint) ,A 

HL 

A, (HL) 
(ppoint+1) ,A 
to first string 
(sdipoint) 
HL, (head) 

DE, (head) 

HL ,HL 

HL , DE 

HL ,BC 
(sdipoint) ,HL 
to second string 
(sd2point) 
HL, (tail) 

DE, (tail) 

HL ,HL 

HL , DE 

HL ,BC 
(sd2point) ,HL 


and address of first 
870 ;string: (slen) & (string) 


HL, (sdipoint) 
A, (HL) 
(slen) ,A 

HL 

A, (HL) 
(string) ,A 
HL 

A, (HL) 
(stringt1) ,A 


970 ;Compare first string to pivot 
980 3;branch to proci if string<pivot 


B,O 

DE, (string) 
HL, (ppoint) 
A, (DE) 

(HL) 
C,proci 

NZ, second 
B 

A, (plen) 

B 












Listing 8.1 


JR Z,second 
LD A, (slen) 
CP B 
JR Z,proci 
INC DE 
INC HL 
JR NZ ,comp 
3Add 3 to sdipoint 
proci: LD HL, (sdipoint) 
LD DE,3 
ADD HL,DE 
LD (sdipoint) ,HL 
sincrement highhead 
INC IX 
JP first 
3Get length and address of 
ssecond string (slen) & (string) 
second: LD HL, (sd2point) 
LD A, (HL) 
LD (slen) ,A 
HL 

LD A, (HL) 

LD (string) ,A 
HL 

LD A, (HL) 

LD (stringt1) ,A 
;Compare second string to pivot 
sbranch to proc2 if string>pivot 

LD B,O 

LD DE, (ppoint) 

LD HL, (string) 

LD A, (DE) 

CP (HL) 

JR C,proc2 

JR NZ ,over 

B 

LD A, (slen) 

CP B 

JR Z,over 

LD A, (plen) 

cP B 

JR Z,proc2 

INC DE 

INC HL 

JR NZ,comp2 
;Subtract 3 from sd2point 
Proc2: AND A 
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1560 
1570 
1580 
1590 
1600 
1610 
1620 
1630 
1640 
1650 


LD 
LD 
SBC 
LD 
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HL, (sd2point) 
DE,3 
HL , DE 
(sd2point) ,HL 


3;decrement lowtail 


DEC 
JP 


Iy 
second 


3;Compare sdipoint to sd2point 


3Br. 


3;Br. skip if 


proc3 if sdipoint<sd2point 


sdipoint>sd2point 


14660 ;if = dec lowtail & inc highhead 


1670 
1680 
1690 
1700 
1710 
1720 
1730 
1740 
1750 
1760 
1770 
1780 
1790 
1800 
1810 
1820 
1830 
1840 
1850 
1860 
1870 
1880 
1890 
1900 
1910 
1920 
1930 
1940 
1950 
1960 
1970 
1980 
1990 
2000 
2010 
2020 


AND 
LD 
LD 


overs: 


JR 
JR 
DEC 
INC 
JP 
sswop string 
procs: 


LD 
LD 
LD 
LD 
LD 
EX 
LD 
LD 
INC 
INC 
DJNZ 


swop: 


A 

HL, (sdipoint) 
DE, (sd2point) 
HL , DE 
C,proc3 

NZ, skip 

IY 

IX 

skip 
descriptors 
B,3 

DE, (sdipoint) 
HL, (sd2point) 
A, (DE) 

C, (HL) 

DE, HL 

(HL) ,C 

(DE) ,A 

DE 

HL 

swop 


3Add 3 to sdipoint 


LD 
LD 
ADD 
LD 


DE,3 

HL, (sdipoint) 
HL , DE 
(sdipoint) ,HL 


ssubtract 3 from sd2point 


AND 
LD 
SBC 
LD 


A 

HL, (sd2point) 
HL ,DE 
(sd2point) ,HL 


3dec highhead:inc lowtail 


INC 
DEC 
JP 


Ix 
Ivy 
first 


3;Set lowhead=head 
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skips LD HL, (head) 
LD (lowhead) ,HL 
3;Set hightail=tail 
LD HL, (tail) 
LD (hightail) ,HL 
sincrement stackcounter 
LD HL, stackcount 
INC (HL) 
;Store highhead & lowtail (IX&IY) 
LD (highhead) , 1X 
LD (lowtail),IY 
3Calc lowtail-lowhead & 
5 hightail-—-highead 
AND A 
LD HL, (lowtail) 
LD DE, (lowhead) 
HL, DE 
EX DE ,HL 
A 
LD HL, (hightail) 
LD BC, (highhead) 
SBC HL,BC 
;Compare results & stack larger 
slimits : process smaller limits 
AND A 
SBC HL,DE 
JR NC, sthigh 
LD HL, (lowhead) 
HL 
LD HL, (lowtail) 
HL 
LD HL, (highhead) 
LD (head) , HL 
LD HL, (hightail) 
LD (tail) ,HL 
JP loop 
LD HL, (highhead) 
HL 
LD HL, (hightail) 
HL 
LD HL, (lowhead) 
LD (head) ,HL 
LD HL, (lowtail) 
LD (tail) ,HL 
JP loop 
;compare stackcounter to zero 
bypass: LD A, (stackcount) 
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CP 18) 
JR Z,finish 
3Pop tail & head from stack 
POP HL 
LD (tail) ,HL 
POP HL 


LD (head) ,HL 
3decrement stackcounter 
LD HL, stackcount 
DEC (HL) 
JP loop 
finish: RET 





Program 8.3 


10 REM TEST PROGRAM: MACHINE CODE 
20 REM QUICKSORT OF A STRING ARRAY 


30 CLS 

40 PRINT"Loading binary file QSSORT" 
SO MEMORY &98FF 

60 LOAD "QSSORT" ,&9900 

70 CLS 

80 INPUT"Sort how many strings"; NUMBERZ 
90 PRINT 

100 REM FILL AND DISPLAY RANDOM ARRAY 
110 DIM A#(NUMBERZ) 

120 head%=1: tail “Z=NUMBERZ 

130 FOR R%=head% TO tailZ% 

140 BS="" 

150 AZ=6*#RND+1 

160 FOR Z%=1 TO AZ 

170 NZ=25*RND 

180 K$=CHR$ (NZ+65) 

190 BS=BS+kKs 

200 NEXT 

210 AS(RZ) =BS 

220 PRINT AS (RZ) 

230 NEXT 

240 PRINT:PRINT 

250 PRINT"SORTING ARRAY" 

260 PRINT: PRINT 

270 START=TIME/300 

280 CALL &9900,head%,tailZ%, @AS (0) 
290 T=TIME/300-START 

300 FOR R%=head% TO tail% 
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PRINT AS(RZ) 
320 NEXT 

330 PRINT 

340 PRINT"STRINGS SORTED=";3 NUMBER 

350 PRINT 

360 PRINT"SORTING TIME="3ROUND(T,2) 3; "SECONDS" 
370 PRINT 

380 INPUT"Another test (Y/N) "3K 

390 KS=UPPERS (KS) 

400 IF K$="Y" THEN ERASE A$:GOTO 70 ELSE END 





Listing 8.2 





10 REM PRODUCING A MACHINE CODE FILE 
20 REM QUICKSORT OF A STRING ARRAY 
30 REM (no assembler needed) 

40 CLS 

50 ADDRESSZ=&9900 

60 sum=0: checksum=38493 

70 FOR NZ=0 TO &1AD 

80 READ BYTES 

90 KZ=VAL ("&"+BYTES) 

100 POKE ADDRESSZ+NZ,KZ% 

110 sum=sum+kKZ% 

120 NEXT 

130 IF sum<>checksum THEN PRINT"ERROR: Check DATA 
statements":GOTO 1640 

140 PRINT"Writing binary file" 
150 SAVE "QSSORT" ,B,&9900,&1AE 
160 END 

170 DATA DD,46E,00,DD,466,01,22,04 
180 DATA 9B,DD,6E,02,DD,446,03,22 
190 DATA 00,9B,DD,6E,04,DD,66,05 
200 DATA 22,02,9B,97,32,18,9B,2A 
210 DATA 02,9B,ED,5B,00,9B,A7,ED 
220 DATA 52,D2,97,9A,DD,2A,02,9B 
230 DATA FD,2A,00,9B,2A,02,9B,ED 
240 DATA 5B,00,9B,19,CB,3C,CB,1D 
250 DATA 54,5D,29,19,ED,4B,04,9B 
260 DATA 09,22,19,9B,7E,32,06,9B 
270 DATA 23,7E,32,0A,9B,23,7E,32 
280 DATA OB,9B,2A,02,9B,ED,5B,02 
290 DATA 9B,29,19,09,22,14,9B,2A 
300 DATA 00,9B,ED,5B,00,9B,29,19 
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310 DATA 09,22,16,9B,2A,14,9B,7E 
320 DATA 32,07,9B,23,7E,32,08,9B 
330 DATA 23,7E,32,09,9B,06,00,ED 
340 DATA 5B,08,9B,2A,0A,9B,1A,BE 
350 DATA 38,13,20,20,04,3A,06,9B 
340 DATA BS,28,19,3A,07,9B,B8, 28 
370 DATA 04,13,23,20,E9,2A,14,9B 
380 DATA 11,03,00,19,22,14,9B,DD 
390 DATA 23,C3,74,99,2A,16,9B,7E 
400 DATA 32,07,9B,23,7E,32,08,9B 
410 DATA 23,7E,32,09,9B,06,00,ED 
420 DATA 5B,0A,9B,2A,08,9B, 1A,BE 
430 DATA 38,13,20,22,04,3A,07,9B 
440 DATA BS,28,1B,3A,06,9B,B8, 28 
450 DATA 04,13,23,20,E9,A7,2A,16 
460 DATA 9B,11,03,00,ED,52,22,16 
470 DATA 9B,FD,2B,C3,B4,99,A7,2A 
480 DATA 14,9B,ED,5B,16,9B,ED,52 
490 DATA 38,09,20,33,FD,2B,DD,23 
500 DATA C3,37,9A,06,03,ED,5B,14 
510 DATA 9B,2A,16,9B,1A,4E,EB,71 
520 DATA 12,13,23,10,F7,11,03,00 
530 DATA 2A,14,9B,19,22,14,9B,A7 
540 DATA 2A,16,9B,ED,52,22,16,9B 
550 DATA DD,23,FD,2B,C3,74,99,2A 
540 DATA 02,9B,22,0C,9B,2A,00,9B 
570 DATA 22,12,9B,21,18,9B,34,DD 
580 DATA 22,10,9B,FD,22,0E,9B,A7 
590 DATA 2A,0E,9B,ED,5B,0C,9B,ED 
600 DATA 52,EB,A7,2A,12,9B,ED,4B 
610 DATA 10,9B,ED,42,A7,ED,52,30 
620 DATA 17,2A,0C,9B,E5,2A,0E,9B 
630 DATA E5,2A,10,9B,22,02,9B,2A 
640 DATA 12,9B,22,00,9B,C3,1F,99 
650 DATA 2A,10,9B,E5,2A,12,9B,E5 
460 DATA 2A,0C,9B,22,02,9B,2A,0E 
670 DATA 9B,22,00,9B,C3,1F,99,30 
680 DATA 18,9B,FE,00,28,0F,E1,22 
690 DATA 00,9B,E1,22,02,9B,21,18 
700 DATA 9B,35,C3,1F,99,C9 











Producing an object code file 


A convenient way to use machine code subroutines from within a 
BASIC program is to produce a binary file of the object code on tape 
or disc. This can then be loaded automatically by a BASIC program 


Producing an object code file 


in the first few lines. There are two ways to produce the object code 
file: 


Method 1: Using an assembler 
This method assumes that you are in possession of the HiSoft 
DEVPAC assembler. 


1 Load the HiSoft DEVPAC assembler at, say, address 6500 
decimal. You will be prompted for this address. 

2 Type in the assembly code listing exactly as printed in Listing 8.1 
(this is sometimes called the source code listing). 

3 Save a copy of the source code on tape by typing: 

P 10,2610,<filename> 

The file can be reloaded at some later time with: 

G,,<filename> 

4 Assemble the source code by typing an ‘A’ as an assembler 
command. When asked for table size, respond with 500. This is 
more than adequate space for the symbol table. 

5 Clear typing errors if any errors are reported. 

6 Produce an object code file that can be loaded directly from tape 
by a main program. This is done automatically by typing the 
assembler command: O,,QSSORT 

Note that the filename QSSORT is not enveloped in double quotes 
as is normal with BASIC programs. 

7 Perform a hard reset to clear memory. 

8 Type in the test program, Program 8.3. This will automatically 
load, run and test the QSSORT file you have just produced. 

The object code itself is loaded into a section of memory reserved 
above HIMEM at &9900. This allows sufficient memory above 
HIMEM for the object code and, in the case of the CPC464, a 
permanently allocated cassette buffer area. 


Method 2: No assembler 

Type in Listing 8.2 and RUN it. The object code file will be 
produced automatically on tape or disc. This program is simply a 
loop which picks up the machine code bytes from DATA statements 
and dumps them directly into memory from &9900 onwards. The 
code is then automatically saved on tape. 


Relocation of machine code 

The main disadvantage of method 2 is that the code will only 
execute at address &9900. Moving it elsewhere in memory will 
result in chaos because the object code is not relocatable. If for any 
reason you need the code located in memory, other than at &9900, 
you must employ Method 1 and reassemble the source code at the 
alternative address. This is an easy task with Listing 8.1 — simply 
change the address in the EQU statement in line 30 and reassemble. 
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Calling QSSORT from any user program 

To CALL the machine code QSSORT routine it is necessary to pass 
over a few parameters. This is accomplished by the insertion of one 
line in your program. For instance, 

CALL &9900,head% ,tail%,@A$(0) will sort the array A$ 

The &9900 term is the execution address of the subroutine. This 
can be altered if you assemble the code elsewhere in memory. 

The integer variable, head%, is the first item in the array to be 
included in the sort (usually set to 1.) 

The integer variable, tail%, is the highest indexed array element 
to be included in the sort. That is to say if head% is set to 1 and 
tail% is set to 200 then the above call will sort the array A$ from 
A$(1) to A$(200). Even parts of arrays may be sorted if head% and 
tail% are set to index subsections of the array. 

The @A$(0) parameter passes over the base address of the array 
to be sorted. An added bonus is that other arrays in memory can be 
sorted using the same routine. For example, the base address of the 
array B$ could be specified, in which case the last CALL parameter 
would be @B§$(0). In BASIC we would need a separate sort routine 
for each array. 

Note that the ‘@’ symbol preceding a variable means pass over 
the address of the variable to the machine code routine, not the 
variable value itself. 

When a CALL statement is executed in BASIC, the parameter 
list values following the execution address are passed over to the 
machine code subroutine. These are automatically stored in a 
parameter block, offset from an address stored in the IX register of 
the Z80 microprocessor. The parameter list values are offset from 
the IX register contents in the reverse order to that which appears in 
the CALL statement. For instance, with the above CALL, the 
address of the A$(0) string descriptor is set up in (IX) and (IX+1), 
the actual value of tail% is set up in (IX+2) and (IX+3) and finally 
the value of head% is set up in (IX+4) and (IX+5), the order being 
low byte first, high byte second. These parameters may then be 
picked up and stored in a more convenient section of memory by 
the machine code subroutine itself. 

To give an idea of the execution speed that can be expected from 
the assembled subroutine see Table 8.10. The improvement in 
execution time over the BASIC version is, I think you will agree, 
worthwhile. 


Table 8.10 Typical execution times for the machine code Quicksort 


String array size Sorting time (sec) 
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Upgrading the Index processor of Chapter 7 


The complete index processor, Program 7.2, described in Chapter 7 
would greatly benefit from the increased speed of this machine code 
version of Quicksort. The few modifications are given below: 


1 Delete the existing string Quicksort subroutine (lines 1370 to 
1530) 

2 Replace it with the following subroutine: 

1370 REM STRING QUICKSORT 

1380 PRINT “Processing: Please wait” 

1390 head% =1:tail% =L% 

1400 CALL &9900,head% ,tail%,@A$(0) 

1410 RETURN 

3 Change line 30 to the following: 

30 MEMORY &98FF 

4 Add the following lines in order to load the object code file 
prepared above: 


44 CLS:PRINT “Load machine code file” 
45 LOAD “QSSORT”,&9900 


It is more convenient if a copy of the object code file is placed on 
the same disc or immediately after the index processor program on 
tape. Line 110 of Listing 8.2 gives the appropriate SAVE command 
from BASIC. 


Machine code Quicksort of a rectangular string array 


Listing 8.3 is the source code for sorting a rectangular string array of 
the type described earlier in this Chapter. It is fast. In fact, it will sort 
a computerful of records in about 2 seconds. However, successful 
operation depends on the field index being the first DIMensioned. 
That is to say the rectangular array is dimensioned DIM 
A$(FIELDS%,RECORDS%) and individual fields F%, of record 
R%, are accessed A%(F%,R%). 


Listing 8.3 


;QUICKSORT OF A 
;RECTANGULAR STRING ARRAY 
begins EQU #9900 

top: EQU begin+#200 


tails EQU top 

head: EQU topt2 
array: EQU topt4 
Plen: EQU toptd 
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90 slen: EQU topt7 
100 string: EQU topts 
110 ppoint: EQU topti10 
120 offset: EQU topti2 
130 bytes: EQU topti4 


140 lowhead: EQu top+ié 
150 lowtail: EQuU top+18 
160 highhead: Eau top+20 
170 hightail: EQU top+22 
180 sdipoint: EQU topt+24 
190 sd2point: EQu topt+26 
200 stackcount: EQU top+28 
210 psdpoint: EQu topt+29 
220 ORG begin 

230 s;Initialise locations 

240 SUB A 

250 LD (offsett+1),A 

260 LD (bytes+1) ,A 

270 LD (stackcount) ,A 


280 ;Pick up base address of array 
290 ;string descriptors: (array) 


300 LD L, (IX) 
310 LD H, (IX+1) 
320 LD (array) ,HL 


330 ;Pick up field sort index 
340 ;multiply by three: (offset) 


350 LD A, (1X+2) 
360 LD B,A 

370 SLA A 

380 ADD A,B 

390 LD (offset),A 


400 ;Pick up number of fields, add i 
410 ;then multiply by 3: (bytes) 


420 LD A, (1X+4) 

430 Inc A 

440 LD B,A 

450 SLA A 

460 ADD A,B 

470 LD (bytes) ,A 

480 ;Pick up tail of array: (tail) 
490 LD L, (1X+6) 

500 LD H, (I1X+7) 

510 LD (tail) ,HL 

520 ;Pick up head of array: (head) 
530 LD L, (I1X+8) 

540 LD H, (I1X+9) 


550 LD (head) ,HL 
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3Branch to bypass if head>=tail 
570 loop: LD HL, (head) 


580 LD DE, (tail) 

590 AND A 

600 SBC HL,DE 

610 JP NC ,bypass 

620 ;Initialise highhead and lowtail 
630 LD IX, (head) 

640 LD IY, (tail) 


650 ;Calculate pivot string 
660 ;descriptor address : (psdpoint) 





670 LD HL, (head) 
680 LD DE, (tail) 
4690 ADD HL,DE 

700 SRL H 

710 RR L 

720 EX DE, HL 

730 LD A, (bytes) 
740 LD B,A 

750 LD HL,O 

760 mult: ADD HL,DE 

770 DJNZ mult 

780 LD DE, (array) 
790 ADD HL,DE 

800 LD (psdpoint) ,HL 


810 ;Get length and address of 
820 ;pivot string =: (plen) & (ppoint) 


830 LD DE, (offset) 
B40 ADD HL,DE 

850 LD A, (HL) 

860 LD (plen) ,A 

870 INC HL 

880 LD A, (HL) 

890 LD (ppoint) ,A 
900 INC HL 

910 LD A, (HL) 

920 LD (ppoint+1) ,A 
930 3;Set pointer to first string 





940 ;descriptors (sdipoint) 


950 LD HL,O 

960 LD DE, (head) 
970 LD A, (bytes) 
980 LD B,A 

990 mult2: ADD HL,DE 
1000 DIJNZ mult2 


DE, (array) 
HL , DE 
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LD (sdipoint) ,HL 
3;Set pointer to second string 
sdescriptor: (sd2point) 
LD HL,O 
LD DE, (tail) 
LD B,A 
ADD HL,DE 
DJNZ mult3 
LD DE, (array) 
ADD HL,DE 
LD (sd2point) ,HL 
3Get length and address of first 
sstring: (slen) & (string) 
first: LD HL, (sdipoint) 
LD DE, (offset) 
ADD HL,DE 
LD A, (HL) 
LD (slen) ,A 
HL 

LD A, (HL) 

LD (string) ,A 
HL 

LD A, (HL) 

LD (string+1) ,A 
;Compare first string to pivot 
sbranch to proci if string<pivot 

LD B,O 

LD DE, (string) 

LD HL, (ppoint) 

LD A, (DE) 

CP (HL) 

JR C,proci 

JR NZ, second 

B 

LD A, (plen) 

CP B 

JR Z,second 

LD A, (slen) 

CP B 

JR Z,proci 

INC DE 

INC HL 

JR NZ ,comp 
3Add bytes to sdipoint 
proci: LD HL, (sdipoint) 

LD DE, (bytes) 
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ADD HL,DE 


































1500 LD (sdipoint) ,HL 
1510 ;increment highhead 

1520 INC IX 

1530 JP first 


1540 ;Get length and address of 
1550 ;second string (slen) & (string) 
1560 second: LD HL, (sd2point) 


1570 LD DE, (offset) 
1580 ADD HL,DE 

1590 LD A, (HL) 

1600 LD (slen) ,A 
1610 INC HL 

1620 LD A, (HL) 

1630 LD (string) ,A 
1640 INC HL 

1450 LD A, CHL) 

1460 LD (stringt1) ,A 


1670 ;Compare second string to pivot 
1680 ;branch to proc2 if string>pivot 





1690 LD B,O 

1700 LD DE, (ppoint) 
1710 LD HL, (string) 
1720 comp2: LD A, (DE) 

1730 CP (HL) 

1740 JR C,proc2 
1750 JR NZ ,over 
1760 INC B 

1770 LD A, (slen) 
1780 CP B 

1790 JR Z,over 

1800 LD A, (plen) 
1810 CP B 

1820 JR Z,proc2 
1830 INC DE 

1840 INC HL 

1850 JR NZ, comp2 


1860 ;Subtract bytes from sd2point 
1870 proc2: AND A 


1880 LD HL, (sd2point) 
1890 LD DE, (bytes) 
1900 SBC HL,DE 

1910 LD (sd2point) ,HL 
1920 ;decrement lowtail 

1930 DEC IY 

1940 JP second 


s;Compare sdipoint to sd2point 
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3;Br. 


3Br. skip if 


procS if sdipoint<sd2point 


sdipoint>sd2point 


sif = dec lowtail & inc highhead 


AND 
LD 
LD 


over: 


JR 
JR 
DEC 
INC 
JP 
s;swop string 
procs: 


LD 
LD 
LD 
LD 
LD 
LD 
EX 
LD 
LD 
INC 
INC 
DJNZ 


A 

HL, (sdipoint) 
DE, (sd2point) 
HL, DE 
C,proc3 
NZ,skip 

IY 

IX 

skip 
descriptors 
A, (bytes) 

B,A 

DE, (sdipoint) 
HL, (sd2point) 
A, (DE) 

C, (HL) 

DE,HL 

(HL) ,C 

(DE) ,A 

DE 

HL 

swop 


3Add bytes to sdipoint 


LD 
LD 
ADD 
LD 


DE, (bytes) 
HL, (sdipoint) 
HL , DE 
(sdipoint) ,HL 


ssubtract bytes from sd2point 


AND 
LD 
SBC 
LD 


A 


HL, (sd2point) 


HL, DE 
(sd2point) ,HL 


3dec highhead:inc lowtail 


INC 
DEC 
JP 


Ix 
IY 
first 


3;Set lowhead=head 


LD 
LD 


skips 


HL, (head) 
(lowhead) , HL 


3;Set hightail=tail 


LD 
LD 


HL, (tail) 
(hightail),HL 


sincrement stackcounter 


LD 


HL, stackcount 
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INC (HL) 
;Store highhead & lowtail (IX&IY) 
LD (highhead) , IX 
LD (lowtail) ,IY 
3;Calc lowtail-lowhead & 
3 hightail—-highead 
AND A 
LD HL, (lowtail) 
LD DE, (lowhead) 
HL ,DE 
EX DE,HL 
A 
LD HL, (hightail) 
LD BC, (highhead) 
SBC HL,BC 
;Compare results & stack larger 
slimits : process smaller limits 
AND A 
SBC HL,DE 
JR NC ,sthigh 
LD HL, (lowhead) 
HL 
LD HL, (lowtail) 
HL 
LD HL, (highhead) 
LD (head) ,HL 
LD HL, (hightail) 
LD (tail) ,HL 
JP loop 
LD HL, (highhead) 
HL 
LD HL, (hightail) 
HL 
LD HL, (lowhead) 
LD (head) ,HL 
LD HL, (lowtail) 
LD (tail) HL 
JP loop 
s;compare stackcounter to zero 
bypass: LD A, (stackcount) 
CP f¢) 
JR Z,finish 
3;Pop tail & head from stack 
POP HL 
LD (tail) ,HL 
POP HL 
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2890 LD (head) ,HL 
2900 ;decrement stackcounter 
2910 LD HL ,stackcount 


2920 DEC (HL) 
2930 JP loop 
2940 finish: RET 





Program 8.4 is a test program produced to set up a random array 
of 3 field records for testing purposes. The 3 fields are numbered 
field zero, field 1 and field 2 respectively and the array is dimen- 
sioned DIM (FIELDS%,RECORDS%), where fields% is set to the 
value 2. If this appears strange, see the remarks earlier in this 
Chapter concerning the use of rectangular arrays. You are asked for 
the number of records, and which field (0 to 2) is to be the subject of 
the sort. As before, the routine can be called not only from the 
BASIC test program but from any other program by 
CALL &9900,head% , tail% , FIELDS % , FIELDNUM%.@A$(0,0) 

The parameters required are: 


1 The execution address. This is &9900, providing the source code 
is assembled as set by the EQU directive in line 30 of Listing 8.3. 
2 head%, is the minimum indexed array element to be included in 
the sort (usually set to 1). 

3 tail%, is the maximum indexed array element to be included in 
the sort. 

4 FIELDS%, the number of fields minus one or the value to which 
the fields are DIMensioned. 

5 FIELDNUM%, the sorting field number (0 to n—1) where n is the 
total number of fields. The routine can sort records with up to 85 
fields which is a limit well above the demands of most files! 

6 The @A§$(0,0) term passes the base address of the array A§. 


Program 8.4 


10 REM TEST PROGRAM 

20 REM MACHINE CODE QUICKSORT OF 

30 REM A RECTANGULAR STRING ARRAY 

40 CLS 

SO PRINT"Loading binary file QSRSORT"” 
60 MEMORY &98FF 

70 LOAD" QSRSORT" ,&9900 


80 CLS 

90 INPUT"Sort how many 3 field records";RECORDS~” 
100 FIELDSZ=2: REM 3 fields (0,1 & 2) 

110 INPUT"Sort which field (0-2)"3;FIELDNUM% 

120 IF FIELDNUMZ<O OR FIELDNUMZ>2 THEN 110 

130 PRINT 





Program 8.4 


REM FILL AND DISPLAY RANDOM ARRAY 
DIM A¢(FIELDS%,RECORDS%) 
head%=1: tai 1 Z=RECORDS% 
FOR R%=head% TO tail% 
FOR F%=0 TO FIELDS% 
B$="" 

A%=6*RND+1 

FOR Z%=1 TO Ax 
N%Z=25*RND 

K#=CHR$ (N%+65) 

BS=BS+KS 

NEXT 

At (F%,R%) =BS 

PRINT AS(F%,R%) , 

NEXT 

NEXT 

PRINT: PRINT 
PRINT"SORTING ARRAY" 
PRINT: PRINT 
START=TIME/300 

CALL &9900,head%,tail%,FIELDS%,FIELDNUM%, @AS (0 


T=TIME/300-START 

FOR R%=head% TO tail% 

FOR F%=0 TO FIELDS% 

PRINT A$(F%,R%) , 

NEXT ~ 

NEXT 

PRINT 

PRINT"RECORDS SORTED="; RECORDS” 

PRINT 

PRINT"SORTING TIME="3ROUND(T, 2) 5 "SECONDS" 
PRINT 

INPUT"Another test (Y/N) "skK¢ 

K$=UPPER$ (K$) 

IF K#="Y" THEN ERASE A$:GOTO 80 ELSE END 








Producing an object code file of Listing 8.3 

The source code assembles its object code where we instruct it to. In 
the listing, this happens to be &9900 onwards as set in line 30. We 
now need a copy of this object code on tape for use by any other 
program. Again there are two methods, depending on whether or 
not an assembler is available. Brief notes on how to perform this are 
set out below. For more general instructions and comments refer 
back to the QSSORT example earlier. 
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Method 1: Using the HiSoft DEVPAC Assembler. 

1 Load the Assembler at, say 6500 decimal. 

2 Type in Listing 8.3. 

3 Save the source code file by typing: P 10,2940,<filename>. 

4 Assemble the source code file by entering the assembler com- 
mand A. When asked for table size, respond with 500. 

5 Save the object code on tape by typing the command: 
O,,QSRSORT. 

6 Performa hard reset then type in Program 8.4. This program will 
load, run and test the object code file you have just produced. 


Method 2: No assembler required 
Simply type in and RUN Listing 8.4. 

This program produces an object code file named “QSRSORT” 
directly. Unfortunately, the machine code generated in this way is 
not relocatable and thus executes only at address &9900. 


Listing 8.4 


10 REM PRODUCING A MACHINE CODE FILE 

20 REM QUICKSORT OF A RECTANGULAR 

30 REM STRING ARRAY 

40 REM (no assembler needed) 

50 CLS 

60 ADDRESSZ=&9900 

70 sum=0: checksum=46997 

80 FOR NZ=0 TO &1F2 

90 READ BYTES 

100 KZ=VAL ("&"+BYTES#) 

110 POKE ADDRESSZ+NZ,KZ% 

120 sum=sumtKZ 

130 NEXT 

140 IF sum<>checksum THEN PRINT"ERROR: Check DATA 

statements":GOTO 170 

150 PRINT"Writing binary file" 

160 SAVE "QSRSORT" ,B,&9900,&1F3 

170 END 

180 DATA 97,32,0D,9B,32,0F ,9B,32 

190 DATA 1C,9B,DD,45E,00,DD,4646,01 

200 DATA 22,04,9B,DD,7E,02,47,CB 

210 DATA 27,80,32,0C,9B,DD,7E,04 
DATA 3C,47,CB,27,80,32,0E,9R 
DATA DD,46E,06,DD,446,07,22,00 
DATA 9B,DD,6E,08,DD,44,09,22 
DATA 02,9B,2A,02,9B,ED,5B,00 
DATA 9B,A7,ED,52,D2,DC,9A,DD 
DATA 2A4,02,9B,FD,2A,00,9B,2A 





02,9B,ED,5B,00,9B,19,CB 
3C,CB,1D,EB,3A,0E,9B,47 
21,00,00,19,10,FD,ED,5B 
04,9B,19,22,1D,9B,ED,5B 
0C,9B,19, 7E, 32,06, 9B, 23 
7E,32,0A,9B,23,7E,32,0B 
9B,21,00,00,ED,5B,02,9B 
3A,0E,9B,47,19,10,FD,ED 
5B,04,9B,19,22,18,9B,21 
00,00,ED,5B,00,9B,47,19 
10,FD,ED,5B,04,9B,19,22 
1A,9B,2A,18,9B,ED,5B,0C 
9B,19,7E,32,07,9B,23,7E 
32,08,9B,23,7E,32,09,9B 
06,00,ED,5B,08,9B,2A,0A 
9B, 1A,BE,38,13,20,21,04 
34,06, 9B, BS, 28, 1A,3A,07 
9B,B8,28,04,13,25,20,E9 
2A,18,9B,ED,5B,0E,9B,19 
22,18,9B,DD,23,C3,AA,99 
20, 1A,9B,ED,5H,0C,9B,19 
7E,32,07,9B, 23, 7E,32,08 
9B, 23,7E,32,09,9B,06,00 
ED, 5B, 0A, 9B, 2A,08,9B,1A 
BE ,38,13,20,23,04,3A,07 
9B,B8,28,1C,3A,06,9B,Ba 
28,04,13,23,20,E9,A7,2A 
1A,9B,ED,5B,0E,9B,ED,52 
22,1A,9B,FD,2B,C3,F0,99 
A7,2A,18,9B,ED,5B,1A,9B 
ED, 52,38,09,20,36,FD,2B 
DD, 23,C3,7C,9A,3A,0E,9B 
47,ED,5B,18,9B,2A,1A,9B 
1A,4E,EB,71,12,13,23,10 
F7,ED,5B,0E,9B,2A,18,9B 
19,22,18,9B,A7,2A,1A,9B 
ED,52,22,1A,9B,DD,23,FD 
2B,C3,AA,99,2A,02,9B,22 
10,9B,2A,00,9B,22,146,9B 
21,1C,9B,34,DD,22,14,9B 
FD, 22,12,9B,A7,2A,12,9B 
ED,5B,10,9B,ED,52,EB,A7 
20,16,9B,ED,4B,14,9B,ED 
42,A7,ED,52,30,17,2A,10 
9B,E5,2A,12,9B,E5,2A,14 
9B, 22,02,9B,2A,16,9B, 22 
00,9B,C3,3A,99,2A,14,9B 


Listing 8.4 
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E5,2A,16,9B,E5,2A,10,9B 
22,02,9B,2A,12,9B,22,00 
9B,C3,3A,99,3A,1C,9B, FE 


00,28,0F ,E1,22,00,9B,E1 
22,02,9B,21,1C,9B,35,C3 
3A,99,09 





For an idea of the sorting times to be expected for various 
numbers of randomly generated three-field records, see Table 8.11. 


Table 8.11 Typical execution times for the rectangular string array 
Quicksort 


String array size Sorting time (sec) 





Upgrading the filing system of Chapter 7 


The complete filing system, Program 7.1 described in Chapter 7 
would greatly benefit from the increased speed of this machine code 
sorting subroutine. Proceed as follows: 


1 Delete the existing sort routine. 
2 In its place type the following subroutine: 


1490 REM QUICKSORT FILE 

1500 GOSUB 2410 

1510 head% =1:tail% =L% 

1520 CALL &9900,head%, tail% , fields % ,F% ,@A$(0,0) 
1530 RETURN 


3 Change line 30 to: 
30 MEMORY &98FF 
4 Add the following lines: 


44 CLS:PRINT “Load machine code file” 
45 LOAD “QSRSORT”,&9900 


It is convenient to place a copy of the object code file on tape 
immediately after Program 7.1. This enables Program 7.1 to load the 
code without the user needing to swap cassettes in the Datacorder. 
If you have a disc drive, place the file on the same disc. 


Upgrading the filing system of Chapter 7 


Searching arrays 


Searching for a particular item within an array is a common pro- 
cessing requirement, even more common than sorting. Although 
integer arrays are used in the examples, they can easily be converted 
for use with string arrays. 


Sequential or linear search 

This is the search algorithm most widely used and involves starting 
from the beginning of a list and sequentially comparing each 
element in turn with the search key. When the end of the list is 
reached and no match has been found the search is deemed to have 
failed. We used this simple technique in Programs 7.1 and 7.2. 
Subroutine 8.10 is an uncluttered demonstration program of this 
simple technique. The subroutine starting at line 10,000 is simple 
and does not require further explanation. The preceding lines 
generate an array containing sequential odd numbers. Thus only 
odd numbers will be present in the array. RUN the program with, 
say, 1000 elements and see how long it takes either to find or 
determine that the specified integer, entered into item% in line 100, 
is not present in the array. Compare the search times with those 
given for the more efficient binary search given in Subroutine 8.11. 


Subroutine 8.10 


10 REM SEQUENTIAL SEARCH EXAMPLE 

20 CLS 

30 INPUT"How many numbers in list";NUMBERZ 
40 DIM AZ(NUMBERZ) 

50 FOR NZ=1 TO NUMBERZ 

60 AZ(NZ) =NZ#2-1 

70 PRINT AZ(NZ) 

80 NEXT 

90 PRINT 

100 INPUT"Search for "sitemZ 

110 START=TIME/300 

120 GOSUB 10000 

130 T=TIME/300-START 

140 IF flag%Z=1 THEN PRINT"Item found at array posi 
tion"3;J% ELSE PRINT"Item not found" 

150 PRINT"Searching time="3;ROUND(T,2); "Seconds" 
160 INPUT"SEARCH AGAIN (Y/N) "3k¢ 

170 KS=UPPERS (K$) 

180 IF K$="Y" THEN 90 

190 END 

200 ' 

210 ° 

9999 REM SEQUENTIAL SEARCH SUBROUTINE 
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JZ=1 
WHILE JZ<NUMBERZ% AND itemZ< >AZ(J%) 
IZ=IZ+1 


WEND 
IF itemZ=AZ(JZ) THEN flag%Z=1 ELSE flag%Z=0 
RETURN 





Sequential searching, although relatively easy to understand and 
program, is obviously slow because, on average, half the file will 
need to be searched before the required data is found. In other 
words, there will be on average N/2 comparisons for N items in the 
search list. 


The binary search 

A much faster method of searching an array, provided it is first 
sorted, is called the ‘binary’ search. The algorithm is demonstrated 
in Subroutine 8.11. The calling part of the listing is similar to that of 
Subroutine 8.10. 


Subroutine 8.11 










10 REM BINARY SEARCH EXAMPLE 
20 CLS 

30 INPUT"How many numbers in list";NUMBERZ 

40 DIM AZ(NUMBERZ) 

SO FOR NZ=1 TO NUMBER” 

60 AZ(NZ) =NZ#2-1 

70 PRINT AZ (NZ) 

80 NEXT 

90 PRINT 

100 INPUT"Search for "sitem% 

110 START=TIME/300 

120 GOSUB 10000 

130 T=TIME/300-START 

140 IF flagZ=1 THEN PRINT"Item found at array posi 

tion"shigh% ELSE PRINT"Item not found or array not 
in order" 

150 PRINT"Searching time=";ROUND(T,2);"Seconds" 
160 INPUT"SEARCH AGAIN (Y/N) "3K 

170 K$=UPPER$ (K$) 

180 IF K#="Y" THEN 90 

190 END 

200 ° 

210 ° 

9999 REM BINARY SEARCH SUBROUTINE 

10000 low%=1: hi ghZ=NUMBERZ 




























Searching arrays 


10010 WHILE high%>lowZ 

10020 mid%=(lowZ+high%) \2 

10030 IF itemZ>AZ(mid%~) THEN lowZ=mid%+1 ELSE high 
Z=mid% 


10040 WEND 
10050 IF itemZ=A%(high%) THEN flag%=1 ELSE flag%=0 
10060 RETURN 


Assume the array has first been sorted into ascending order, the 
data item in the middle of the list is first compared with the item to 
be matched. If the item is smaller than the required item, the search 
continues in the first half of the array. If the item is larger, the search 
concentrates on the second half of the array. On locating which half, 
the process continues as before by first testing the middle item in 
that half. Eventually, by continually halving, and testing, the 
required data item is either found or declared to be non-existent. On 
the surface, this may seem a longer process than the simple 
sequential search but this is only because it has taken longer to 
explain. The equation of interest is 

Average number of comparisons=LOG,(N) 
where N is the total number of data items to be searched. 

This is a startling result and worth an example, if only to illustrate 
the superiority of the binary search over the simple sequential 
search. Assume we wish to locate a specific item from within a total 
list of 10,000 items. We will compare both methods 


1 Sequential search: Average number of comparisons=N/2= 
10,000/2=500 

2 Binary search: Average number of comparisons=LOG,(N)= 
LOG (10,000)=10 (when rounded). 


Even with one million items, the number of comparisons would 
only be 20. However, it is only fair to stress once more that a binary 
search can only be carried out on a previously sorted array, whereas 
the sequential search makes no demands at all on the order of the 
file items. If an array is small in size, it may not always be worth 
troubling to sort it and it certainly would not be sensible to sort it 
just for the sake of using a binary search. On the other hand, if an 
array has to be sorted for other reasons, then it would be silly not to 
employ binary search. 


Summary 


1 The exchange sort is simple but slow. The execution time in- 
creases roughly proportional to the third power of N. 

2 The bubble sort is faster than the exchange sort. The execution 
time increases at a rate roughly equal to 0.5 times the square of N. 
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3 The insertion sort works out roughly twice as fast as the bubble 
sort. The execution time increases at a rate roughly equal to 0.25 
times the square of N. 

4 The selection sort performs more comparisons than the insertion 
sort but with fewer exchanges. Simple and efficient for sorting 
rectangular arrays. 

5 A Shellsort can still use insertion techniques but first sorts items 
that are far apart in the array. That is to say, a large increment is 
used for comparisons and exchanges. The final sorting pass takes 
place with an increment of one. 

6 The Quicksort is fast on average but performance can 
deteriorate under certain circumstances when the array is ordered 
or near-ordered. The hazard is reduced statistically if the midpoint 
item in the array is taken as the pivot. 

7 We may approach the minimum sorting speed of large randomly 
ordered arrays if we machine code the Quicksort algorithm. 

8 Understanding of machine code string sorting is made easier if 
the details of the String Descriptors are known. 

9 File records can be stored in two dimensional array form. 

10 A particular item in an array can be located by either a simple 
sequential search or, if in order, a binary search. 
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Clearly written and readable 
introduction to Z80 machine 
code on the Amstrad CPC 464 
and 664 It explains binary and 
hexadecimal arithmetic and 
contrasts the pros and cons of 
machine code against BASIC 
The book includes a hex 
loading program, for those 
working without an assembler, 
and the Amstrad Assembler/ 
Disassembler 
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